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Organization of This Book 


This reference book describes the functions available in the 
Application Prototype Environment Version Two Licensed Program. 
The functions are divided into the following chapters: 


è Chapter 1, “Introduction” provides some genera! background 
information about Application Prototype Environment Version 2. 


¢ Chapter 2, “Screen-Handling Functions” describes the functions 
that control panel input and output, manage the display of tutorial 
panels, check panel key usage, and perform many other 
operations on panels created with Panel Design (PDESIGN). 


è Chapter 3, “Chart Functions” describes the functions that perform 
various operations on charts created with Chart Design 
(CDESIGN). 


¢ Chapter 4, “File-Handling Functions” describes the functions that 
control file input and output, check the status of files, and perform 
a wide range of operations on file declarations created with File 
Design (PDESIGN). 


è Chapter 5, “Query Functions” describes the functions that allow 
you to create or modify SQL objects associated with Query Design 
(QDESIGN). 


e Chapter 6, “Object Library Functions” describes the functions that 
help you manage storage and retrieval of application objects 
through the use of object libraries. Many of the object library 
functions are provided as PF keys and list commands in Object 
Library Design (ODESIGN). 


è Chapter 7, “Auxiliary Functions” describes the functions that you 
use primarily during application development for checking and 
managing the various types of objects in the workspace. 


è Chapter 8, “Utility Functions” describes the functions that are 
designed to save the application programmer time by providing a 
wide assortment of general-purpose functions for use in APL code. 


e Chapter 9, “Miscellaneous Functions” describes the functions that 
perform operations on menus created with Menu Design 
(MDESIGN), on lists created with List Design (LDESIGW), on 
images created with Image Design (IDESIGN), as well as 
providing some other general-purpose functions. 
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Chapter 1. Introduction 


Terminology 


The fotlowing are some of the key terms used in this book, For a 
complete list of terms, see the “Glossary” on page 229. 


Name list 


Panet list 
Label list 
Object fist 


Current panel 


A list of names in a character vector, a matrix, or a 
vector of vectors. Names in a character vector are 
normally separated by blanks, commas, or slashes. A 
matrix might contain rows of names that are separated 
in the same way as for character vectors. Each 
element in a vector of vectors must be a single name 
to qualify as a name list. 


A name list of panel names. 
A name list of label names. 
A name list of objects. 


A panel image is built in storage before it is displayed 
on the screen. This image might also be modified with 
data and attributes before display. After display, for 
example, with SMOD, the image is retained in storage 
for possible further modifications and redisplay. Thus 
the current panel is set by any of the display functions. 
It might also be set by the SDISP function. The 
current panel is maintained until it is either replaced 
by another current panel, or is explicitly cleared by the 
SCLEAR function. The current panel is maintained 
both by GDDM and Application Prototype Environment. 
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Naming Conventions 


To avoid conflicts if names are duplicated, Application Prototype 
Environment uses a standard naming convention for alt internal 
coding. As a result, you should not: 


4. Use the A symbol as the first character in a name. 
2. Use an over ` or under _ bar in the second position of a name. 


3. Use names that are the same as product functions or variables (for 
example, PDESIGN, QDESIGN, SMOD, and so on). 


Normatly in Application Prototype Environment: 


1. Functions and operators are named with non-underscored letters 
from A to Z. 


2. Auxiliary and utility functions and operators start with the A_ 
symbols. 


3. Operators end with the A symbol. 


4. Global variables are named with all letters underscored. 


Object Type Codes 


Object type codes are used to identify and distinguish objects of 
different types in the workspace or in an object library. An object 
type code is a single letter such as P for panels; this code is followed 
by a colon and the name of the object. Several of the Application 
Prototype Environment functions use object type codes to refer to 
specific types of objects. 


The object type codes are: 


Menu applications 
Charts 

File declarations 
Functions 
Images 

Lists 

Menus 
Operators 
Panels 

Queries 
Variables 


SOPORTAR 


In addition to the above codes, the object library uses the type codes 
G and E for a group of library objects and for a jibrary-latent 
expression, respectively. 


Online Help Information 


Online information is available for the functions described in this 
book. There are two ways of viewing the online help information for 
individual functions: 


1. Type the A_SHOW function in the APL2 session manager followed 
by the name of one of the functions in the product. For instance, 
you would type the following expression to view help information 
on the SMOD function: 


A_SHOW 'SMOD' 


2. Type FUNCTIONS in the APL2 session manager or on the 
command line of any of the Application Prototype Environment 
menus. This function displays a menu from which you can display 
lists of the various functions in Application Prototype Environment. 
From these lists you either type the SHOW command or press a 
PF key to view a help panel for individuat functions in the list. 
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Chapter 2. Screen-Handling Functions 


This chapter contains a description of all screen-handling functions. 


For general information on using screen-handling functions and on 
creating panels, refer to Application Prototype Environment: Guide. 
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COPY_ID and GCLEAR 


COPY _ID — Define Print File 


Purpose To define a filename to be used by graphical printout functions. 


Syntax COPY _ID 


Usage Notes 
COPY_ID produces a name to be used as a filename by graphical 
print functions such as SPRI. The default is a name such as 
APEnnnnn where nnnnn is the time of day in seconds. 


If you wish, you may edit the COPY_TID function to change the 
filename to a name of your choice, 


GCLEAR — Clear Graphics Field 


Purpose To clear any graphics field on the current panel. 


Syntax  GCLEAR 


GDDM 


GDDM — Obtain AP126 Call Number 


Purpose To give the AP126 call number for any of the available GDDM macros. 
Syntax Z + GDDM M 
M the name of a GDDM macro. 


Example CTLS + (GDDM'FSQURY'),0 1 18 a Query terminal 
VAR + CTLS a characteristics 


Usage Notes 
The AP126 call number is returned and can be used for direct calls to 
the GDDM Auxiliary Processor (AP126). The tables used by the 
GDDM function are updated at the beginning of a terminal session, 
and thus will always give the latest status of possible GDDM calls. 


An example of communicating with GDDM is shown in Figure 1. 


C 1] a| Call CSSEC 0 to define a graphics segment, set character mode to 3. 
E 


2J a| (Call GSCM), and query the size of the character box (call GSQCB). 
[ 3] al It is assumed that the current panel contains a graphics field. 


i 8] CTL + (CDDM'GSSEG'),0,( GDDM'GSCM'),3,GDDM'CSQCB! 
[9] ** SCHK RC + CTLE 


C15] CB + ~24RC a Extract character box size 


(21) a Set the character box to twice the size (call GSCR) and 
[22] 8 write APE at the coordinates (10,10) (call GSCHAR) 
[23] a and finally close the graphics segment. 


(33) DATS + ‘APE! 
C34] CTLS + (GDOM'GSCB'),(2*CB),(GDDM'GSCHAR'),10,10,3,G0DM'GSSCLS* 
(35) "' SCHK RC + CTLE 


Figure 1. Communicating Directly with GDDM. Calls GDDM in order to write the letters ‘APE’ using twice the 
normal character size. The letters will be written into the graphics field of the current panel. 
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PANFNWS and PDESIGN 


PANFNS — Display List of Screen-Handling Functions 


Purpose To display a list of the available screen-handling functions. 
| Syntax PANFNS 


ae 


Usage Notes 
The list includes a short description of each of the screen-handling 
functions. For more information, use the SHOW command or the PF 10 
key against any of the functions in the list. 


PDESIGN — Call the Panel Design Menu 


Purpose To call the Panel Design (PDESIGN) menu. 


z 
i 
i 
| 


Syntax PDESIGN 


Usage Notes 
Displays a menu containing options for designing panels. 


PLIST and SALE and SBMOD 


PLIST — Display List of Panels 


Purpose To show a list of all user-created panels. 
Syntax PLIST 
Usage Notes 


You can use commands and PF keys to perform operations on the 
panets in the list. Press PF 1 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 


SALE — Set Audible Alarm 


Purpose To set the audible alarm. 
Syntax SALE 
Usage Notes 


Sounds the audible alarm at the next display. 


SBMOD — Test for Modified Fields 


Purpose 


Syntax 


Example 


Result 


To determine which specified fields have been modified. 
Z2*SBMOD V 
V isa label list. 


Z isa numeric vector containing an element for each field specified. The value is 1 if the 
corresponding ficld was modified during the last input operation and 0 otherwise. 


Z + SBMOD 'MEMBNO' 
1 


The 1 shows that the field MEMBNO has been modified. 
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SBRMOD 


SBRMOD — Browse and Edit Panel Variables 


Purpose To browse and edit selected variables in a panel and, optionally, to specify the names of one 
or two processing functions. 


Syntax V SBRMOD X 


x 


Vv 


Usage Notes 


is a vector of the form P A B, where: 


P 
A 


is one panel name. 


(optional) is an initjalization function. Itis the name of an APL function that is 
called during browse/edit initialization. If not used, specify a (place holder) if 
option B is to be used. 


(optional) is a processing function. It is the name of an APL function that is 
called during browse/edit command processing. 


is a character vector or matrix specifying one or more browse groups. 


A browse group has the form D WN, where: 


D 


(optional) indicates direction of movement of variables that are to be linked 
together, as follows: 


+or+ variables can be scrolled vertically. 

>or+ variables can be scrolled horizontally. 

(none) variables can be scrolled both vertically and horizontally. 
(Numeric fields can only be browsed vertically.) 


is the name of a variable or a sequence of variable names, separated by blanks, 
that make up a group. The panel P must contain all labels specified. 


For information on using SBRMOD, see “SBRMOD/SBROUT -- Usage 
Notes” on page 16. 
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SBROUT 


SBROUT — Browse Panel Variables 


Purpose To browse selected variables in a panel and, optionally, to specify the names of one or two 
processing functions. SBROUT works in the same way as SBRMOD, except that 
variables are protected and cannot be modified. 


Syntax V SBROUT X 


X isa vector of the form P A B, where: 


P is one panel name. 

A (optional) is an initialization function. It is the name of an APL function that is 
called during browse/edit initialization. If not used, specify a (place holder) if 
option B is to be used. 

B (optional) is a processing function. It is the name of an APL function that is 
called during browse/edit command processing. 

Vis a character vector or matrix specifying one or more browse groups. 


A browse group has the form D N, where: 


D 


Usage Notes 


(optional) indicates direction of movement of variables that are to be linked 
together, as follows: 


tor+ variables can be scrolled vertically. 

>or+ variables can be scrolled horizontally. 

(none) variables can be scrolled both vertically and horizontally. 
(Numeric fields can only be browsed vertically.) 


is the name of a variable or a sequence of variable names, separated by blanks, 
that make up a group. The panel P must contain all labels specified. 


For information on using SBROUT, see “SBRMODISBROUT -- Usage 
Notes” on page 16. 
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SBRKEYS — Alter PF Key Operations and Text 


Purpose To alter the operations of the PF keys and the ENTER key in an SBRMOD/SBROUT 
processing function. 


Syntax T SBRKEYS K 


T is the text that describes the action of the specified PF key; this text will be displayed 
at the bottom of the panel. 


K isa numeric vector of five elements for specifying the following: 


K(1] is the number of the PF key to be modified. Actually, the command 
code number, which by default is the PF key number, is used. This 


K[2] state is a number, in the range 1-4, specifying the state to be used in 
connection with the specified PF or ENTER key, as follows: 


state | Browse mode. Variables may be browsed and modified. PF 
keys are enabled for terminating and entering edit mode. 


state 2 Edit mode. Variables may be browsed and modified. PF keys 
are enabled for inserting, deleting, moving, and duplicating 
lines. 


state 3 Place mode. The MOVE PF key has been pressed and some 
lines are pending. 


state4 Recover mode. The DELETE PF key has been pressed and 
some lines are pending delete or recover. 


K[ 3] action / is a code for specifying which action is to be performed first, after 
pressing the specified key. The codes are specified from the list shown in 
Figure 2 on page 13. 


KIs] action 2 is a code for specifying another action to be performed after pressing 
the specified key. The codes are specified from the list shown in 
Figure 2 on page 13. 


KES] nxt-state is a number in the range 0-4 to specify the state to be used after 
pressing the specified PF key, where: 


e O specifies that SBRMOD/SBROUT is terminated after the user's 
processing function is completed. 
è 1-4 as described under “state” above. 
Example ‘Scroll diagonally’ SBRKEYS 12 2 12 0 2 


Result When using SBRMOD in cdit mode, change description of PF 12 to scroll diagonally, and 
set the action and states as specified in K. 
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SBRKEYS 


Usage Notes 


SBRKEYS can only be used within an SBRMOD/SBROUT processing 
function. 


Action 


No Operation 

Terminate browse 

Make screen, copy (call SPRI) 

Go to edit’ mode 

Scroll backwards 

Scroll forwards 

Scroll to top if cursor is in upper half, 
else scroll ta bottom 

Scroll left 

Scroll right 

Scrol} diagonal ly down to cursor if 

no data modified and ENTER is pressed, 
reverse operation for not ENTER key. 
Exclude lines pointed out by cursor 
Terminate edit mode, and issue 

edit complete message 

Insert lines as indicated by cursor 
Repeat lines as indicated by cursor 
Insert pending lines at cursor position 
Recover pending lines into original position 
Final delete of pending lines 


Table of Possible PF Key Actions 


Figure 3. 
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Table for Default Setting of PF Key Actions 


For information on using SBRKEYS, see “SBRMOD/SBROUT — 
Usage Notes” on page 16. 
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SBRSTATE — Determine or Set State 


Purpose To determine the current and next state and, optionally, to set a new state in an 
SBRMOD/SBROUT processing function. 


Syntax A + SBRSTATE S 
A is atwo-element vector, as follows: 
AC 1] is the current state. 
A(2] is the next state to be entered after user processing has terminated. 
S is a numeric scalar in the range 0-2 to specify the next state to be used, where: 


O specifies that, after user processing is completed, SBRMOD/SBROUT is 
terminated. 


1 specifies browse mode for SBRMOD/SBROUT. 
2 specifies edit mode for SBRMOD. 


Usage Notes 
SBRSTATE can only be used within an SBRMOD/SBROUT 
processing function. 


A two-element vector is returned indicating the current state and the 
next state. You cannot enter edit mode directly from browse made. If 
S is empty or invalid, the next state will not be changed; thus, you can 
query the current state by specifying S as empty. 


For more information on using SBRSTATE, see “SBRMODISBROUT 
-- Usage Notes” on page 16. 
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SBRWINDOW 


SBRWINDOW — Determine or Set Coordinates 


Purpose To determine and, optionally, to set the coordinates of a variable in a panel browse window 
in an SBRMOD/SBROUT processing function. 


Syntax A + V SBRWINDOW C 


A 


Usage Notes 


is a four-element vector, as follows: 

A[1] contains the index of the top row of the data about to be displayed. 

AC 2] contains the index of the leftmost column of the data about to be displayed. 
A(3] contains the index of the top row of the data last displayed. 

AC4 ] contains the index of the leftmost column of the data last displayed. 

is the name of a browse variable. 


is a two-element, numeric vector specifying the coordinates of the new position of the 
window, as follows: 


CE1] is the row number 


CE2] is the column number. 


SBRWINDOW can only be used within an SBRMOD/SBROUT 
processing function, (fee Side 2) 


A four-element vector is returned. If C is empty or invalid nothing 
further happens; otherwise the data is moved to the coordinates 
specified in C. This means that you can query the current coordinates 
by specifying C as empty. 


Oniy those coordinates associated with the browsing direction 
specified in SBRMOD are returned; other coordinates are set to zero. 


If the coordinates specified in C are too large, they are set to the 
maximum value determined by the variable. 


For more information on SBRWINDOW, see “SBRMOD/SBROUT — 
Usage Notes” on page 16. 


Chapter 2. Screen-Handling Functions 15 


SBRMOD/SBROUT — Usage Notes 


SBRMOD/SBROUT -- Usage Notes 


Usage without a Panel Name 


tf you have a character matrix called VAR that you want to view and 
scroll, use the SBROUT function: 


'VAR' SBROUT '' 
If you also want to update VAR, use the SBRMOD function: 
'VAR' SBRMOD '' 


You can now browse through your matrix vertically and horizontally. 
The use of the PF keys is shown at the bottom of the screen, and the 
rest of the screen is used to display your matrix. 


With SBRMOD, you can now make changes, and when you have 
finished (by pressing PF 3) your matrix will contain the new updates. 


Note: There is no way to erase the changes you have made. If you 
want to be able to erase the changes, you have to save a copy of the 
matrix before you use SBRMOD. 


If you want to edit your matrix by inserting, deleting, or moving lines 
around, you can press PF 6. This will take you into edit mode. The 
bottom PF key use notation is changed, since the operation of the PF 
keys changes. 


You can: 

e Insert tines by using PF 4. 

e Delete lines with PF 5. 

e Duplicate lines by pressing PF 6. 
* Move lines with PF 2. 

. 


End edit mode by pressing PF 3. 


PF Key Usage — Browsing and Editing 


The use of the PF keys is shown in the following tables. Note, 
however, that the usage of the PF keys is dependent on the setting of 


correspond exactly to the PF key numbers shown in the following 
tables. 
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The PF keys used in browse mode are shown in Figure 4. 


PF Key Operation Explanation 
Operation (SBRMOD, SBROUT) 
1 HELP Enters the tutorial at the page indicated in the last 
call to SHELP. 
NO OPERATION 
END Terminates SBRMOD/SBROUT. 
COPY Creates a hard copy of current screen (through 
SPRI). 
5 NO OPERATION 
6 ENTER EDIT SBRMOD only. 
MODE 
7 UP Moves the display window up towards the top of 
the data. 
8 Moves the display window down towards the 


TOP/BOTTOM 


RIGHT 


SCROLL 
FORWARD 


bottom of the data. 


Alternates between showing the top and bottom. 
parts of the data. 


Moves the display window towards the left edge of 
the data. 


Moves the display window towards the right edge 
of the data. 


Moves the display window up/left. 
Moves the display window down/night. 


Figure 4. PF Key Operations in Browse Mode 
The follawing figure shows the PF key operations that change when 
you enter edit mode under SBRMOD. The other keys have exactly the 
same operations as before. 
The PF keys used in edit mode are shown in Figure 5. 
PF Key Operation Explanation 
Operation (SBRMOD) 
2 | MOVE/PLACE Moves one or more lines to a new position. 
3 | END Terminates edit mode. 
4 | INSERT Inserts one or more lines after a specified row. 
5 DELETE/RECOVER Deletes one or more lines from the screen after 
verification. 
6 | REPEAT Repeats one or more lines. 
Figure 5. PF Key Operations in Edit Mode 


17 


Chapter 2. Screen-Handling Functions 


SBRMOD/SBROUT — Usage Notes 


How to Use the PF Keys 


Forward — ENTER Key 


Scroll — PF 12 


End — PF 3 


Move/Place — PF 2 


To scroll with the ENTER key, position the cursor in the desired field 
and press ENTER. 


Note the following: 


Ifthe variable can be scrolled vertically only, the row indicated by 
the cursor will be the new top row, 

© If the variable can be scrolled horizontally only, the column 
indicated by the cursor will be the new left column. 

è If the variable can be scrolled in both directions, the position 
indicated by the cursor will be the new top, left position. 


To scroil with PF 12 is the reverse of scrolling with the ENTER key. 


e If a variable can be scrolled vertically only, the top row will be at 
the cursor position. 

è If a variable can be scrolled horizontally only, the left column will 
be at the cursor position. 

e If a variable can be scrolled in both directions, the field will be 
moved so that the top, left position of the field will be at the cursor 
position. 


To end SBRMOD/SBROUT, you must use the END key; therefore, do 
not define other functions for this key, otherwise you will not be able 
to exit. 


Note: This is different from using SMOD, where you can use any key 
to exit. 


To move one or more lines in a scroll group: 


1. Position the cursor in the first line to be moved in the scroll group. 

2. Select the number of lines to be moved by placing the cursor 
under: column 1, to move one line; column 2, to move two lines; 
and so on. 

3. Press PF 2 and the number of lines indicated by the cursor 
position are removed from the screen. 

4. Position the cursor to the line after which the data is to be 
inserted. 
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Insert — PF 4 
Delete — PF 5 
Repeat — PF 6 


5. Press PF 2 and all fields in the scroll group are moved to the new 
position. 


For example, to move lines 4, 5, and 6 after line 2, place the cursor on 
line 4 in column 3 and then press PF 2. Next, move the cursor 
anywhere under line 2 and press PF 2 again. 


To insert one or more lines after a specified row: 


1. Position the cursor in the row in the scroll group (insertion will 
take place after this line). 

2. Select the number of lines to be inserted by placing the cursor 
under: column 1, to insert one line; column 2, to insert two lines; 
and so on. 

3. Press PF 4 and those lines indicated by the cursor position will be 
inserted in all fields belonging to the selected scroll group. 


For example, to insert two lines after line 3, place the cursor on line 3 
in column 2 and press PF 4. 


To delete one or more lines: 


1. Position the cursor in the first row to be deleted in the scroll 
group. 

2. Select the number of lines to be deleted by placing the cursor in: 
column 1, to delete one line; column 2, to delete two lines; and so 
on. 

3. When PF 5 is pressed, those tines indicated by the cursor position 
are removed from the screen. 

4. To complete deletion, press ENTER; or, 

5. To recover the data, press PF 5 once again. 


For example, to remove lines 2 and 3, place the cursor on line 2 in 
column 2 and press PF 5; next, press ENTER. 


To repeat (copy) one or more lines: 


1, Position the cursor in the first row to be repeated in the scroll 
group. 

2. Select the number of lines to be repeated by placing the cursor in: 
column 1 to repeat one line; column 2, to repeat two lines; and so 
on. 

3. When PF 6 is pressed, those lines indicated by the cursor position 
are repeated after the tast line of the lines to be repeated. 


Chapter 2. Screen-Handling Functions 19 


SBRMOD/SBROUT — Usage Notes 


For example, to repeat lines 5 and 6, place the cursor on line 5 in 
column 2 and press PF 6. Lines 5 and 6 are then copied below line 6. 


Usage with a Panel Name 


If you want to scroll through your matrix in your own panel, you need 
to have a panel containing a window with the same name as your 
variable. The result is the same as for SMOD or SOUT, except that 
one or more windows can be browsed (and edited). Other data that is 
not browsed is treated exactly as in SMOD and SOUT. Thus, on one 
panel you may combine data that you cannot browse with data that 
you can browse. 


lf the bottom two lines of the display screen are not occupied by the 
panel text, two lines showing the PF key functions are inserted. This 
is useful because SBRMOD automatically changes the bottom line of 
text, depending upon the current operation mode. 


If your panei name is PAN, the instruction now will be 
‘VAR' SBRMOD 'PAN' 


For browsing the variable VAR, the operations are exactly the same 
as described earlier. You can, however, have other data fields, both 
output and input, in your panel and use these the same way as you da 
when you, for example, use SMOD to display your panel. 


Note: The only difference in this respect is how the instructions 
(SBRMOD and SMOD) are terminated. SMOD is terminated with any of 
the interrupt keys — ENTER or PF key ~ whereas SBRMOD is only 
terminated when the termination key (normally PF 3) is pressed. Note 
also that you can initiate termination of SBRMOD yourself at any time 
by using a processing function. Thus it is possible to make SMOD 
and SBRMOD behave identically. 


Specifying Scrolling Direction 


If you only want to browse your data vertically, you can specify this 
scrolling direction in the left argument. The direction indicators are 
the APL arrows. 


't VAR' SBRMOD 'PAN' 


The arrow can be placed anywhere in the left argument, and both the 
upward and downward arrows allow vertical scrotling (browsing). Just 
as in SMOD, your variable has to fit into your window in the 

non-browse direction. If it does not, the window is filled with asterisks 
to indicate that the variable is too large to fit into the available space. 
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The scrolt indicators have the following values: 


+ or + scrolls fields horizontally only 
tor + scrolls fields vertically only 
omitted scrolls fields both horizontally and vertically 


Scrolling Two Variables in Parallel 


To scroll two variables in parallel, you of course need two 
corresponding windows in your panel. For example, to link the 
scrolling of two variables, you might specify: 


‘+ VAR1 VAR2' SBRMOD 'PAN' 
The left argument is now called a scroll group. 


Note: tn this case SBRMOD will make the number of rows in the two 
matrices equal to the number of rows in the longest matrix. This is to 
ensure synchronous operation on both variables that you have 
specified. For the same reason insertions, deletions, repetitions, and 
moving of lines will be made in parallel on both variables. 


Scrolling Two Variables Separately 
If, on the other hand, you want to scroll your two variables 
independently of each other, you specify two individual scroll groups, 
each group with one variable in it. To do this, the left argument of 
SBRMOD must be a matrix, with one group to a line — in this case 
one name to a line. This could be coded as follows: 

('VAR1' A_MAD 'VAR2') SBRMOD 'PAN' 
You now have two scroll groups, each containing one variable. 

Example of Several Scrol! Groups 
As an example, data about employees (employee number, name, 


address, city, and telephone number) might be arranged as shown in 
Figure 6. 
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Longroad 2045  Bigtown 123456 


etc. etc. 


Figure 6. Scrolling Variables with SBRMOD/SBROUT 
In this example, the employee data is too long and too wide to be 
displayed in the window. Therefore, you decide that you would like to 
do the following: 


e Scroli up and down, as well as to the sides. 


+ Scroll the header columns and the employee numbers 
synchronously with the data. 


Assume that you currently have: 

e A panel with windows as shown in Figure 6. 

e Named the top window TOP. 

è Named the employee window SIDE. 

è Named the data window DATA. 

* Created a variable called TOP, which contains the text for the 


column headers (except the text ‘Emp. No.’, which is static) and is 
as wide as your data. That is: 


TOP+'<---Name---~><--Address------ ><-Cily----><-Telephone->' 


e Created a variable called SIDE, which contains the employee 
numbers, and which is not wider than the window but is as long as 
your data variable. 


è Put the body of your data in the variable DATA 


To create the scrolling result you want, you link your windows as 
follows: 


('+SIDE DATA’ A_MAD '+TOP DATA') SBRMOD 'PAN' 
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Now the first scroll group, that is, the employee number and the data, 
will scroll together vertically — and the headers will stay in place. The 
headers will scroll sideways together with your data, but the 
employee numbers will stay in place. 


Ending Scrolling 


To end scrolling, you must use the END key, or code the termination 
yourself in your own processing function. Note that this is different 
from SMOD, which allows you to use any key to exit. 


Some Notes on Scrolling 


When specifying scrolling with SBRMOD/SBROUT, you should also 
note the following: 


e Numeric fields can only be scrolled vertically. If the direction 
indicator is missing in the left argument, implying that scrolling is 
allowed both up/down and left/right, then one of two messages is 
returned: 


1. If the numeric variable is not a matrix, then the message 
“Rank error for browsing” is returned. 

2. If the numeric variable is a matrix, then the message “ 
Numeric variable can only be browsed vertically” is returned. 


è When you are scrolling with more than one scroll group, 
SBRMOD needs to know which group to scroll. You must 
therefore place the cursor somewhere within the group to be 
scrolled to identify it. This is not needed when you only use one 
scroll group. 


* If scroll variables are missing, SBRMOD issues the message 
VALUE ERROR. 


e Ifa variable can be scrolled in one dimension only, the other 
dimension must fit the window. 


¢ Scrolling is done with the PF scroll keys, which normally are PF 7 
(UP) and PF 8 (DOWN), and PF 10 (LEFT) and PF 11 (RIGHT). For 
information on altering the PF key assignments, see “Using 
PEKEY” on page 80. 


e Scrolling can also be done with the ENTER key and the PF 12 key. 
For more information about the use of these PF keys, see “PF Key 
Usage — Browsing and Editing” on page 16. 
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e The left-hand side of the tast example: 
('+SIDE DATA’ A_MAD '*TOP DATA‘) 


is just a matrix. The A_MAD function combines the two character 
strings into a matrix with the following format: 


+SIDE DATA 
«TOP DATA 


Initialization and Processing Functions 


You may add your own functions to the operations of 
SBRMOD/SBROUT. A flowchart of SBRMOD/SBROUT processing is 
shown in Figure 7 on page 25. This figure shows that you can 
specify an initialization function after SBRMOD/SBROUT initialization 
but before the panel is displayed. Your processing function is called 
when the user presses any key and before transition to the next state 
(that is, before the next action is performed). For example, you may 
want to prevent the user from terminating (transition to state 0) from 
an error situation; instead you might want to display an error message 
and await the user’s response. 
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Call SBRMOD/SBROUT 


v 


User Initialization functlon 


v 


Write alt variables 
to the screen and +—> 
wait for user action 


Execute key actions 


v 
v 

User Processing Function 
v 


Transfer to new state 


E 


Figure 7. Flowchart for SBRMOD/SBROUT Processing 


Using an Initialization Function 


if you want to do some special processing just before your data is 
displayed, for example to change the operation of some PF keys, you 
can do that in the initialization function. Assume that you want your 
user to be able to change data by typing over it, but that you do not 
allow any additions, deletions, or moving around of data. You will then 
want to inhibit the use of PF 6 to take the user into edit mode. 


You could code the initialization function as follows: 


0) VINIT 
[1) '' SBRKEYS61001 


In the above example, when PF 6 is pressed in browse mode (state 
1), actions 1 and 2 have no operation, and the next state is browse 
mode (state 1). In the default situation, when PF 6 is pressed in 
browse mode (state 1), action 1 is processed (causing a switch to edit 
mode), action 2 is not processed, and the next state is edit mode 
(state 2). For a list of possible actions and the default settings, see 
Figure 9 on page 32 and Figure 10 on page 33. 
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Note: The empty vector as the left argument in statement 1 causes 
the text to be taken away for PF 6 on the bottom PF key line in the 
panel. 


Now your SBRMOD expression will be: 


('tSIDE DATA' &_MAD '+TOP DATA') SBRMOD ‘PAN INIT' 


The initialization function is called after all normal SBRMOD 
initialization has taken place, but before any data is displayed on the 
screen. 


Note: This function is called and executes as a subfunction of 
SBRMOD. You should be careful to avoid name conflicts with the 
SBRMOD/SBROUT functions. For a description of Application 
Prototype Environment naming conventions, see “Naming 
Conventions” on page 2. 


In this function you would normally: 
e Use SBRKEYS to alter the operation of the PF key usage. 


* Do other preparatory work not performed outside and before 
SBRMOD was entered. 


Do not try to set state 2 with SBRSTATE in this function to go directly 
to the edit mode. Doing that will not initiate state 2 operations of the 
PF keys properly. 


Be very careful not to eliminate the ability to get to state 0 (to 
terminate). If you alter the operation of the PF 3 operation, be sure to 
have some other way of exiting. If you do not, your terminal might 
become locked with the panel just displayed. To be able to get out of 
this situation you might have to force an end to your session and lose 
whatever programs and data were entered since the last time you 
saved the data. 


Using a Processing Function 


If you, for example, allow users to enter edit mode to add or delete 
data, but you want to check the validity of data operations, you would 
code a processing function that gets control every time the terminal is 
interrupted by the user. 


With a processing function called PROC, your expression could be: 


('+SIDE DATA’ &_MAD '+TOP DATA') SBRMOD ‘PAN INIT PROCt 
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Processing States 


Note: If you want to specify a processing function without an 
initialization function, you must insert a place holder for the second 
subargument. The expression would then be written: 


('4#SIDE DATA’ &_MAD '+TOP DATA') S8RMOD ‘PAN R PROC' 


For an example of how you can code and use these functions, see 
Figure 8 on page 30. 


The processing function is called after all command processing has 
been completed and immediately before any required state transition 
takes place. 


The processing function serves the following main purposes: 
è It acts on data entered by the user. 


You may supply code to process data entered either in the 
browsed variables or in other input fields on the panel. 


è It alters the processing sequence by changing the default next 
state 


You should normally check which state you are in, and possibly also 
which is the next state to be entered. 


Note: You must not change the shape of the data using either the 
initialization or the processing function. You must not, for example, 
delete a row of data. This would interfere with SBRMOD’s way of 
keeping track of your data’s placement in the window(s), and result in 
either data being handled erroneously or in an SBRMOD program 
error. If you really need to change the shape of data, you can force 
SBRMOD to end by setting the next state to zero; then you can do the 
operations on your data variable, and enter SBRMOD again. 


The possible processing states are: 


State 1 Browse mode. Data might have been modified by 
over-typing, but new lines have not been inserted. 


State 2. Edit mode. Various data changes might have been made. 


State 3. Place mode. PF 2 has just been pressed to move some 
lines. You should normally not interfere with this operation 
— you have allowed line moves to be done by not inhibiting 
it. The next state should be state 2. 
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Browse Functions 


State 4 Recover mode. PF 5 has just been pressed to erase some 


lines. See also state 3 above. 


Note: If the next state is equal to 0, SBRMOD will terminate 
execution when your own processing function has terminated. 


Normally, your function should check that you are in browse or edit 
mode. In the move/recover and move/place modes you should not 
interfere with SBRMOD. 


To help you do operations both in the initialization function and in the 
processing function, a set of cover functions are available. 


SBRKEYS will help you to set the bottom line PF key text, to 
select amongst the different system actions, and to specify the 
next state. For more information, see SBRKEYS on page 12. 


SBRSTATE will help you to find out the current state of SBRMOD 
and the next state to be entered. The function will also set a 
different next state, if the default next state is not what you want. 
For more information, see SBRSTATE on page 14. 


SBRWINDOW will give the indices of both the preset data display 
and those of the previous displays indices. The function also 
allows you to change these indices. For more information, see 
SBRWINDOW on page 15. 


Terminating the Browsing Operation 


To terminate the browse operations, the next state can be set to 0 
either by: 


The user pressing PF 3. You can check for this condition by using 
the SBRSTATE function. You can inhibit the termination by 
setting another state by using the SBRSTATE function again. 
This might be of interest when the user has modified the data in a 
window, or entered some other invalid data (in a non-browsable 
data field). You might want to send the user an error message and 
force him to stay within SBRMOD, even when he has pressed PF 
3. 


Using the SBRSTATE function yourself. You might find a 
terminating condition that does or does not have a connection with 
the browsed data. For example, when you are browsing and 
updating data from a file, you might detect that the user has 
entered a command in an input field on the panel instead of 
pressing a PF key. You would terminate browsing by setting the 
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next state to zero, and then write the data back to the file — either 
in your processing function, or after terminating SBRMOD in your 
main routine. 


You might want to have other panels that operate underneath your 
SBRMOD function. You must then protect all of your SBRMOD 
environment before doing other screen operations such as SMOD. 
You do this by first calling the SSAVE function before doing the 
internal SMOD. When SMOD has terminated, you call SREST to 
restore the SBRMOD environment and to display your browse panel 
on the screen again. 
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0] PROC ;A;PARM 

1J 

2) 

3J A + SBRSTATE '' 

4] +((AC1}¥.#1 2)vA[2]=1)/0 a Exit if not browse, edit or 


5] a exit requested 
6] a Some more processing and validation 
Cis] 


(16) SSAVE 'X' 
(17) MYSYS?PEM PARM 


Preserve SBRMOD environment and 
call subsystem 


[28] 


(26) 

[27] 

[28] SREST 'xX' a Retrieve and display SBRMOD environment 
(29) a Display message 

[30] '' SMSG ‘Requested operation completed! 


[31] +0 


Figure 8. Saving the Browsing Environment 


Altering the Processing Sequence 


You may use the function SBRSTATE both to find the present and the 
defaulted next state, and to change the new state to something 
different from the defaulted next state. The syntax for this would be: 


present state, next state + SBRSTATE empty 
present state, next state + SBRSTATE next state 


A two-element vector is returned, with the first element indicating the 
present state and the second element the next state. If the right 
argument is empty or invalid, the next state will not be changed 
(SBRSTATE works as a query function). 


If the right argument is a numeric 1 or 2, the next state is set to the 
value of the variable. 


Altering PF Keys and ENTER Key Operations 


When your initialization function is entered, the default PF key 
meanings and actions are set up. In order to change this set-up you 
should use the SBRKEYS function. The syntax for doing this is: 


text SBRKEYS key,state,action1,act ion2,nxt-state 
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where: 


text 


key 


State 


action 


action2 


nxt-state 


The text to be used on the bottom line of your panel to 
explain the use of the specific PF (or ENTER) key. lf this 
is an empty vector, the description of that key is 
completely removed from the PF key information area. 
You must verify that your new PF key text fits within the 
two bottom PF key lines. 


The text is automatically prefixed by the “PF xx =” text 
and placed in its proper place. 


The key to be modified. 0 means the ENTER key. 


Note: This is not the reat PF key number, but rather the 
command code number as assigned to a specific key in 
the PFKEY variable. If you do not change the PF key 


actual key number, 

The state where the key change applies. 

A code for the first of two actions that will be performed 
(see “Key Actions for SBRMOD/SBROUT” on page 32 for 
a description of actian codes available). 


A code for the second action that will be performed when 
this key is pressed. 


The next state SBRMOD will enter after the two actions 
have been performed. 


An example is when you want to remove some lines from your data 
window. To be able to do this, you must be in edit mode (state 2). 
When you then press PF 5, action 1 (code 22) removes the data from 
display. Action 2 (code 0) does nothing, and the next state is state 4, 
which is the delete/recover mode of operation. You can now: 


© Press PF 5 again, in which case action 1 (code 33) reinserts your 
data, and action 2 (code Q) again results in no operation. The next 
state is 2, which is back to normal ‘edit’ mode. 


e Press anything other than PF 5, in which case action 1 (code 35) 
permanently removes the data, and action 2 performs the action 
expected for the key pressed. If you, for example, pressed PF 7, 
action 2 (code 7) is the scrolling operation, and the next state is 
state 2, back to normal edit mode. 
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Key Actions for SBRMOD/SBROUT 


When setting or changing the meaning of PF keys you will need to 
know the action values you can select. 


The following two tables show you the actions that are available, and 
the relationships between states and actions for the different keys. 


(A SE 


Figure 9. 


No Operation 

Terminate browse 

Make screen copy (call SPRI) 

Go to edit mode 

Scroll backwards 

Scroll forwards 

Scroll to top if cursor is in upper half, 
else scroll to bottom 

Scroll left 

Scroll right 


Scroll diagonal ly down to cursor if 


no data modified and ENTER is pressed, 
reverse operation for not ENTER key. 
Exclude Tines pointed out by cursor 
Terminate edit mode, and issue 

edit complete’ message 

Insert lines as indicated by cursor 

Repeat lines as indicated by cursor 

Insert pending lines at cursor position 
Recover pending lines into original position 
Final delete of pending lines 


Possible PF Key Actions 
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State 
BROWSE 
a) 


lst/2nd Next 1st/2nd Next 


PF Key Action State State PF Key Action State 
1=HELP n/a 1 PLACE 1=HELP n/a 3 
3=END 3 0 0 (3) 2=PLACE 322 0 2 
4=SCOPY 4 0 1 3=END 33 23 1 
6=EDIT 6 0 2 4=INSERT 33 24 2 
7=BACKWARD 7? 0 1 5=DELETE 33 22 4 
8=FORWARD 8 0 1 6=REPEAT 33 26 2 
9=T0P/BOT 9 0 1 7=BACKWARD 7 0 3 

1O=LEFT 10 0 1 8 0 3 

11=RIGHT u o0 1 9 0 3 

12=REVERSE 12 0 I 10 0 3 

ENTER 12 0 1 u 0 3 

12 0 3 
ENTER 12, 0 3 


EDIT 1=HELP n/a 2 RECOVER n/a 4 
(2) 2=MOVE 22 0 3 (4) 35 22 3 
3=END 23 0 1 35 23 1 
AsINSERT 24 0 2 35 24 2 
S=DELETE 22 0 4 3 0 2 
6=REPEAT 26 0 2 35 26 2 
7=BACKWARD 7 0 2 3 7 2 
B=FORWARD 8 0 2 35 8 2 
3 0 2 35 9 2 
10 0 2 35 10 2 
L1=RIGHT u o 2 35 1 2 
12-REVERSE 12 0 2 12=REVERSE 35 12 2 
ENTER 12 0 2 ENTER 35 12 2 

Figure 10. Default Setting of PF Key Actions 


The headings in Figure 10 have the following meanings: 


state The states 1, 2, 3, and 4, which correspond to the browse, 
edit, place and recover operation modes. 


key The PF key function. 


Note: This is the PF key function, not the PF key really 
used. It normally corresponds to the true key number if 
you have not altered it yourself by changing the content of 


1 Action 4. 
2 Action 2. 
next The next state. This is the state or mode SBRMOD will 


enter as soon as your processing function has terminated. 
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Get or Set Window Coordinates 


The SBRWINDOW function is used to find where in the window your 
variable is positioned and/or to place it elsewhere in the window. 


The syntax of SBRWINDOW is: 


places + name SBRWINDOW new place 


places A four element vector giving first the indices of the top 
row and the leftmost column about to be displayed, then 
the corresponding indices for the data about to be 
displayed. Directions not participating in scrolling are 
noted as zeros. 


name The name of the window 


new place The new coordinates for the upper left corner of data to 
be displayed next. If the right-hand argument is empty, 
nothing further happens, that is, SBRWINDOW works as a 
query function. 


If your processing function detects that data has been changed in an 
invalid way, and that the user has pressed a scroll key, the function 
can inhibit the scroll (and give the user an error message). To inhibit 
the scroll you could, for example, code the following: 

C..] 

[23] Re'At SBRWINDOW '' 

[24] Re'A' SBRWINDOW 2+R 

Deed 


Example of Termination 


You may want to make some keys available for termination of 
SBRMOD to do some processing outside of the SBRMOD function. 
This could be of interest in cases such as: 


e You want SBRMOD to behave like SMOD, except for the scrolling 
of data. But do not forget that SBRMOD uses more processing 
time than SMOD. 


e You want to change the shape of your browsed data variable. This 
cannot be done inside SBRMOD; that is, in your processing 
function — the internal index variables controlling the placement of 
the variable will then be changed. 


If you wanted PF 5 to take you to a function to insert lines in your 
browsed variable, and PF 6 to take you to an editing function from 
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browse mode, you could code something like wh 


at is shown in 


Figure 11. 

INIT 

a| Special initialization function. Set PF keys. 

‘Data' SBRKEYS 51000 a Cause 'S=Data' to appear, 
‘Run' SBRKEYS 61000 a Cause '6=Run' to appear, 
BROWSE 
al Browse AAA and BBB together 
SHOW: 

'tAAA BBB! SBRMOD 'MYPAN INIT? 

+CSKPF=3 5 6)/0,INSER,XLIN a Check usage of PF keys 
INSER: INSERTXYZ a Insert special data lines 
+SHOW 
XLIN: XDATA a Perform the XDATA routine 


+SHOW 


and terminate 
and terminate 


Figure LL. Example of Termination 


Enable Processing 


You can enabie speciat processing in your processing function for PF2 


in edit mode (replacing the MOVE capability). 


To assign an alternate text to PF2 and set up a processing function, 


you could use the code shown in Figure 12. 


NYPUNC 


‘tBIGGIE' SBRMOD 'PAN15 INIT2 PROC2' 


INIT2 


al Enable own processing of PF2 in edit mode 

'Validate’ SBRKEYS 2 2 0 0 2 a Set no actions; following 
a state is edit (2) 

PROC2 

al Special processing function 

A*SBRSTATE '* a Process PF 2 


~((AL1]=2)ASKPF=2)/VALIDATE a if in edit mode 


Figure 12. Using PF 2 in Browsing Mode 
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Preventing Termination 


You may wish to prevent the user from terminating if user data is 
erroneous, except in the case where the user has specified a QUIT 
command. To accomplish this, you can set the next state to zero 
when the command is detected, and force the next state to be the 
same as the current state if the user tries to exit with erroneous data. 
Figure 13 is an example of code that would handle this situation. 


C0] PROCEXITSAGXPQ 

C 4] AeSBRSTATE '' a Exit if not browse or edit mode 
{C 2] +(AC1] 0.21 27/0 

C 3] 

[ a] *(18A/'QUIP'SUtCOMAREA)/L1 a Exit if QUIT command issued 
[ 5] A*SBRSTATE 0 

C 6] +0 

Ev 

[ 8] L1: +(12EVALUATE XPQ)/0 a Exit if everything is OK 

E 9] a Error message 

[10] ‘A’ SMSG 'Your xpq-number is too small....' 

E11] 

[12] +(A[2]=0)/0 a Return if not ready to exit 
t13] A*SBRSTATE A[1] a Stay if exit requested 


Figure 13. Preventing Termination 


Switching From Edit to Browse Mode 


You can detect that a state transition will take place by comparing the 
two values of the result of SBRSTATES '' with each other. 


If you want to do a special validation on terminating edit and returning 
to browse mode, you could code what is shown in Figure 14. 


C121) wee 
[13] a Check if returning to browse from something else 
C14} A*SBRSTAT '' 


[15] #((A[2]=1)AAC1]22)/BACKTOBROWSE 
E16] .... 


Figure 14. Staying in Edit Mode 
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Example of Using SBRWINDOW 


Assume that there is a panel with a field A that must have a positive 
numeric value less than 10. The processing function might resemble 
what is shown in Figure 15. 


0) XPROC;2;VAL;I;CORD 

1) 

2] Z+SHAPE 'A' a Find window size and data index 
3] CORD+'A' SBRWINDOW '' 

4) VALTAL(CORO(3]-1)+#120151)] 
5J +CA/I+(VAL20 )AVAL<10)/0 

6] I+1t(~I)/ipl 

7] Re'A't SBRWINDOW 24CORD 

8J 'A' SMSC ‘Incorrect value’ 
9] 'A* SCUR 1,1 a Point to incorrect value 


Get the values displayed 

Leave function if all values correct 
Get index of first incorrect value 
Move window to redisplay data 


Figure 15. Using SBRWINDOW 


Tutorials for SBRMOD/SBROUT 


If SHELP has not been used, then a system tutorial will be shown. 
That includes a page on browsing and editing. If, for exampie, you 
use SHELP 'MYTUT', then you may need to include your own 

information on how to use the PF keys when browsing and editing. 


The variables specified in the left argument must have fields defined 
in the panel. The right argument can be specified as an empty vector 
(“), in which case a default panel is generated. For browsing with the 
default panel, only one variable can be specified. Fields in the panel 
not named in V behave as described in the SMOD function. You can 
specify that one or more fields are to be scrolled together. For further 
details, see “Scrolling Two Variables in Parallel” on page 21. 


If the bottom two lines of the display screen are not occupied by the 
panel, SBRMOD inserts two lines showing the PF key functions. if no 
SHELP has been used, then a system tutorial will be shown on 
browsing and editing, 
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SCHK and SCLEAR 


SCHK — Check GDDM Return Codes 


Purpose To check return codes from GDDM calls. 
Syntax E SCHK C 
C is a numeric vector containing the return code from GDDM. 


E isa two column matrix or an empty vector specifying the control variable for AP126. 


Usage Notes 

Left Argument 
An empty vector indicates that any non-zero return code should cause 
an interrupt of the application. For a matrix, specify in the first 
column the return codes and in the second column the corresponding 
reason codes you want ignored in the test. Specifying a reason code 
of —1 will ignore all reason codes within the return code. 

Right Argument 
Do not use the control variable directly as the right hand argument for 
the function, except if you do not want to refer to the returned values 
later. 

Control Variables 


The control variables used for AP126 communication are: 


e DATS for data 
e CTLS for control, 


For examples of usage, see GDDM on page 7. 


SCLEAR — Clear Current Panel 


Purpose To clear the current panel. 


Syntax SCLEAR 
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Usage Notes 
Clears the current panel. Ail delayed panel modifications, set for 
example with SCOL, are canceled. 


SCOL and SCOLI — Change Field Color 


Purpose To change the color of one or more ficlds in the current panel. 


Syntax V SCOL C 
V SCOLI C 


V isa label list. 


C is a numeric vector containing field color codes: 


Default 
Blue 

Red 

Pink 
Green 
Turquoise 
Yellow 
Neutral 


wow oan 


NAUEWN=O 


Example 'MPHASE' SCOL 2 


Result Sets color of field MPHASE to red. 


Usage Notes 
Sets the colors for the specified fields to the values provided by the 
numeric vector C. 


SCOL changes the color on the next update of the current panel; 
SCOLI changes the color immediately on the currently displayed 
panel. 


Note: For a description on how to change the color of individual 
characters in a field, see . . ACA on page 80. 
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SCREENTYPE — Show Terminal Attributes 


Purpose To show terminal attributes. 
Syntax N«SCREENTYPE 
N is a numeric vector of 10 elements, as follows: 


C1] = Screen size in rows 
NC2] = Screen size in columns 
W([3] = Terminal type: 
0 = 3277 
1 = 3278, 3279, 3287, or 8775 
Nu] = APL/text feature: 
0 = no 
1 = yes 
NCS] = Number of colors: 
1 = monochrome and 4-color 3279 or 3287 
7 = seven color 3279 
NC6] = Highlight: 


0 = no 
l= yes 
NCF] Number of PS storages available 
N[8] = Terminal capable of graphics display: 
0 = no 
= yes 


t 
WE9] = Mixed EBCDIC/DBCS support: 
0 = no support 
explicit support 
emulated support 
lining support 
no 
yes 


arn wd 


1 
x 

N[10] = Ou 
o 
1 


Example SCREENTYPE 
32 8601171610900 


Usage Notes 
The test for the APL/text feature may not be available at certain 
installations, in which case NC 4 } always returns a 1, even if there is 
no APL/feature on the particular terminal being tested. 


Note: For N[91, the letter x is the code point corresponding to the 
emulated character. 
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SCUR and SCURT 


SCUR and SCURI — Position Cursor 


Purpose To position the cursor in a field on the current panel. 


Syntax VSscurR ¢ 
V SCURI C 


C is a numeric vector of two elements containing the position of the cursor within the 
field as a row and a column number. 


V is a character vector containing the field label to contain the cursor. 
Example 'MPHASE't SCURI 1 1 


Result The cursor is moved to the top, left-hand position (row 1, column 1) in the field MPHASE. 


Usage Notes 


The cursor is moved to the specified position when the screen is next 
updated, 


SCURT positions the cursor on the next display of the current panel; 
SCURI positions the cursor immediately on the panel that is 
currently displayed. 
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SDISP — Set Current Panel 


Purpose To initiate a new current panel. 
Syntax SDISP P 
P isa character vector containing a panel name. 
Example SDISP 'MINFO! 
Result The panel MINFO is set as the current panel. 
Usage Notes 


The SDISP function initiates a panel as the current panel without 
displaying it on the screen. This can be useful when you prepare for 
a panel to be displayed. Things you might want to do, but which can 
only be done with a current panel, are for example: 

e Setting the cursor at a specific place in the panel (with SCUR). 

è Changing the color of a field (with SCOL). 

è Setting speciat highlighting for a field (with SELT). 

e Using your own symbol set for a field (with SPSS). 


è Changing the attribute of a field (with STYP). 
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SDTUT — Enter Tutorial Mode 


Purpose To display one or more panels in tutorial mode. 


Syntax SDTUT P 
P 


Example SDTUT 


is a panel list specifying the tutorial stack. 


'MINFOTUT' 


Result The first panel in the list of pancls in MINFOTUT is displayed. If the panel names are 
suffixed by numbers, then you can browse through the panels. 


Usage Notes 


Tutorial mode is entered, and the first specified panel is displayed. 


Panel names might contain numeric suffixes to identify them as 
belonging to tutorial books, in which case the entire tutorial book can 
be browsed, 


If a panel name is not part of a tutorial book, the panel will be 
displayed as a single panel. Specifying a nonexistent panel 
(undefined panel) will result in an error message being displayed 
instead of the tutorial. For more information, see SHELP on page 48. 


if the panel list contains more than one panel name, the list of panel 
names constitutes the tutorial stack. That is, when the user presses 
the HELP key after displaying the first panel in the list, the next 
tutorial level is entered with the next panel in the list as the current 
tutorial page. If the user presses the HELP key after the last panel in 
the list has been displayed, a panel explaining the tutorial mode will 
be displayed. 


The pages in the tutorial are browsed using the PF keys. The setting 
of the PF keys is described in “Setting Program Function Keys” on 
page 79. When the individual panels are displayed, one or two lines 
will be inserted on the bottom of the screen, if available, as follows: 


e The second-to-last line describes PF key operations. 


è The last line contains page reference information, where you can 
enter a new page number. 
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SERA and SERAI 


SERA and SERAT — Clear Fields 


Purpose To clear one or more fields in the current panel. 
Syntax SERA V 
SERAI V 
V isa label list. 
Example SERA 'MEMBNO MCITY MPHONE MADDR' 
Result The four fields given as the right argument to SERA are cleared. 
Usage Notes 


Clears the fields specified in V by assigning them a blank content. 


SERA clears the fields before the next update of the current panel; 
SERATI clears the fields on the currently displayed panel. 


Note: If the fields specified are updated by variables from the 
workspace, SERA may appear to have no effect. 
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SFSAVE — Create an ADMSAVE File 


Purpose To save the current panel as an ADMSAVE file for subsequent display by SFSHOW (or 
FSSHOW of GDDM). 


Syntax SFSAVE F 
F isa filename of your choice. 
Example SFSAVE 'MYSAVE' 


Result Saves the current panel as an ADMSAVE file with a filename of MY SA VE. 


Usage Notes 
The current panel is saved on a disk as an ADMSAVE file. The 
filename will be the name specified by F and the filetype will be 
ADMSAVE. The panel can then be redisplayed using the SFSHOW 
function or the FSSHOW function of GDDM. The saved panel can only 
be displayed on the same terminal type as the one on which it was 
created. 


Note: Under TSO, a file with a filetype of ADMSAVE must be created 
prior to using the SFSAVE function. The file can be created as 
follows: 


ALLOC F(ADMSAVE) DA(dataset name) 
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SF SHOW — Display an ADMSAVE File 


Purpose To display an ADMSAVE file saved with the SF SAVE function (or with the FSSAVE 
function of GDDM). 


Syntax SPSHOW F 
P is the name of a saved file. 
Example SFSHOW 'MYSAVE' 


Result Displays a previously saved ADMSAVE file whose filename is MYSAVE. 


Usage Notes 
The panel saved earlier as an ADMSAVE file is displayed. All input 
fields are protected. Only ADMSAVE files created from the same type 
of terminal can be displayed. 
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SHAPE 


SHAPE — Determine Shape of Field 


Purpose To determine the shape of panel fields. 
Syntax Z+[P] SHAPE V 
V isa label list. 
P (optional) is a panel name. 
Z is a two-column, numeric matrix containing a row for each field specified. A row in Z 


contains the size of the corresponding field as number of rows and number of columns. 
If P is an empty vector or omitted, Z returns the shape of specified labels in the current 


panel. 
Example 'MINFO' SHAPE 'MEMBNO MPHONE' 
5a 
Result Returns the size of fields MEMBNO and MPHONE in the panel MINFO. 
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SHELP — Set Tutorial Stack 


Purpose To set the current page of an on-line tutorial. 
Syntax SHELP T 


T is an empty vector, or a name list of panels or variables optionally prefixed or suffixed 
by a semicolon, as follows: 


list of panels{variables 
the list is the tutorial stack. 


slist of panels}variables 
the list is stacked at the bottom of the existing stack. 


list of panels/variables; 
the list is stacked on top of the existing stack. 


the top level in the stack is dropped. 
me the stack is cleared. 
Example SHELP 'PANO1 VAR' 
Result PANO1 is the name of a panel and VAR is a matrix containing the second-level help text. 
When HELP is pressed, panel PAN 01 is displayed; when HELP is pressed again, the 
variable VAR is displayed. 


Example 


on 


ED Peele. 

2] SHELP 'GENERALOS' 
: 
6 


E 
L 


ww 


1 SHELP ‘SPECIFICO6;' 
l 


Result This example shows how to stack SPECIFIC06 in front of GENERALOS. 


Usage Notes 
The panel(s)/variable(s) specified by T will be used as the tutorial 
stack when the HELP key is pressed. If a panel with the supplied 
name does not exist and a variable with the name does exist, then 
SBROUT is called to display the variable. Invalid names in T will be 
detected only after pressing the HELP key. 
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Tutorial Books 


A tutorial book is a collection of panels linked together in sequential 
order. This book is created by defining a matrix containing the names 
of the panels, 


You can use the following two functions to view the pages of a tutorial 
book: 


SDTUT With this function you specify the first page (panel) of the 
tutorial book to be displayed immediately on the screen. 


SHELP With this function you specify the first page to be displayed 
when the HELP key is pressed. 


When displaying tutorials, the system automatically inserts one or two 
lines at the bottom of the tutorial panels, depending on the amount of 
space available: 


* The second to last tine will contain PF key information for the 
tutorial book. 


e The last line will show the current page number in the tutorial 
book; this line also contains an input field where the user can 
enter a page number in order to go directly to another page within 
the same tutorial book. 


Thus, you must leave one blank row at the bottom of your tutorial 
panel if you want the page-select field to be displayed; and two blank 
rows if you want both the page-select field and the PF key information 
to appear. 


Creating Tutorial Books 


When creating tutorial books, the following naming convention should 
be followed: 


è The book can have any valid APL name, but the name should not 
contain any digits. 


e Pages in the book are panel names. At least one of these should 
have the same name as the book itself, plus a numeric suffix. 


To initiate the automatic display of the tutorial with the HELP key, you 
use the SHELP function, where you name one of the pages that has 
the numeric suffix on the book name itself. The page named in the 
SHELP function is the page of the book entered when the HELP key 
is pressed. Thus, every time you display a different action panel, you 
might want to point to the page explaining that particular action panet. 
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SHELP 


The way it operates is as follows: 


Notes on Creating Tutorials 


If the panel named in the SHELP does not have a numerical 
suffix, then that panel is displayed as a one-page tutorial. 


If a numeric suffix exists, the suffix is dropped, and the system will 
look for a tutoria! book with the same name as the stripped page 
name. If such a book is found, it will be used as a tutorial book 
which is entered at the specified page. 


You need to be aware of the following items when creating tutorials. 


Any tutoria! pages that are not to be used in the SHELP function, 
can have any name you choose. 


The numerical suffix itself has nothing to do with page numbering. 


The page number is determined by the place of the page within 
the tutorial book matrix. 


Tutorial panels not found when the book is entered will be 
eliminated as possible pages before the tutorial mode is entered. 
(This is different from using SMOD with a name list. If SMOD finds 
a panel missing from a name list, SMOD will stop execution with 
an error message telling you which panel(s) is/are missing.) 


If you find that your tutorial seems to have fewer pages than you 
expected, maybe one of the names in the book is missing, or has 
been misspelled. 


You might want to have tutorial “minibooks” entered from different 
parts of your application, and at the same time be able to display all 
the tutorial pages in one complete tutorial book selected from your 
main menu. If such selection is made you can then use the SDTUT 
function to enter a tutorial first page which is a table of contents for 
the rest of this complete book. Some examples of minibooks are 
given below. 
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Stacking Tutorials 


In the following example, any of the three pages can be used to find 
minibook SUBA. 


SUBA + A_BX 'SUBA1 SUBA11 SUBAO1' 
SUBA 

SUBA1 

SUBA11 

SUBAO1 


Note: The A_BX function converts the right argument into a matrix. 


In the next exampie, only the second and the fourth page can be used 
in SHELP to find the SUBX minibook. Note, however, that all four 
pages belong to the SUBX tutorial book. 


SUBX + A_BX 'PAGE1 SUBX100 PAGEN SUBX003' 
SUBX 

PAGE1 

SUBX100 

PAGEN 

SUBX003 


In the final example, using SDTUT 'ALLTUT1" will both find the 
ALLTUT1 book and enter tutorial mode directly. You can thus 
browse through ail of the pages even if you can only enter the book 
on the first page. In this case, it would be natural to have the first 
page be a table of contents. 


ALLTUT + >A_MAD/'ALLTUT1234' SUBA SUBX 
ALLTUT 

ALLTUT1234 

SUBA1 

SUBA11 

SUBAO1 

PAGE1 

SUBX100 

PAGEN 

SUBX003 


Note: The A_MAD function joins two matrices as one matrix. 


You can stack tutorials; that is, you can have tutorials behind tutorials. 
You might, for example, want to display a one-panel tutorial page for 
an action panel, and allow the user to press the HELP key again to 
enter a tutorial book explaining matters in more detail. 
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SHELP 


You can stack tutorials using either the SHELP function or the 
SDTUT function: 


® With SHELP, the tutorial is entered with the HELP key. The 
tutorial stack maintained by SHELP is kept in a variable called 
HELP. You might want to make this variable a local variable in a 
function. If you do, you will then automatically both clear that 
function's tutorial stack, and reinitiate the higher level function's 
tutorial stack when you leave the tower level function. (You 
should always use the SHEL P function to set the stack, and not 
set the HELP variable directly yourself.) 

+ With SDTUT, the right hand argument is the tutorial stack. After 
the first panel is displayed using SDTUT, the user enters the next 
tutorial level (if one exists) by pressing the HELP key. SDTUT 
maintains its own stack, and tutorials stacked with SHELP are 
ignored, 


When used, a tutorial page normally has an input field at the bottom 
line where you can specify the new page you want to see. 


Specifying Data Input for Tutorials 


You can also specify data input fields in a tutorial page. Hf data is 
entered in such an input field and ENTER is pressed, the tutorial is 
ended. Consider the following possible situation: 


e You have an action screen with several input fields. 

e You want to explain each one of these in a separate tutorial page. 

è You want to display the particular tutorial page when the user 
enters a “?" instead of normat data in a field. 

è You will allow the user to enter the required value next to the 
explanation in the tutorial itself. 

è You then want to return to the action panel — with the newly 
entered data displayed on it. 


You could then do the following: 


è Create the necessary tutorial pages. 

è Ensure that each tutorial has an input field. 

è Ensure that the particular. tutorial’s input field has the same label 
as the input field it is explaining. 
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SHELP 


You might code it in the following way: 


(21) eee 

[22] SHOW: SMOD 'ACTION' Display action panel 
[23] +(SKPF=3)/0 END if PF 3 

C24] +(~v/FIELD16'2")/NEXT1 Was ? entered in FIELD1 
(25) SOPUT 'HELPFLD1 If so, display tutorial 


[26] +SHOW Redisplay action panel 
[27] WEXT1: *(~v/PIELD2€'2')/NEXT2 a Was ? entered in FIELD2 
[28] SDTUT ‘'HELPFLD2 If so, Display tutorial 
(29) sees 


Figure 16. Tutorials with Input Fields 


You would create a tutorial book called HELPFLD in which the user 
could scroll and enter values on any of the tutorial pages. 


When the action panel is redisplayed on line [ 22}, the following 
might have occurred: 


èe The user might have browsed the tutorial book with the browse 
keys, or indicated a new page number in the page number field. 


e Any data the user entered in any of the tutorial pages will be 
visible on the action panel. 


e Any data the user might have entered before entering the tutorial 
has been shown on the tutorial page where that particular variable 
is explained. If the user changed it, the changed value will be 
shown on the action panel. 


è The tutorial mode was ended either by using the END key (PF 3) or 
by pressing ENTER in one of the panels where values could be 
entered. (By using ENTER, the tutorial page has become a data 
entry panel.) 


Example of Using Tutorial Panels Containing Input Fields 
You can use tutorial panels containing input fields instead of 
presenting a series of tutorial panels that contain only text. Consider 
the following situation: 


è You have an action panel containing three input fields. 


+ You do not have enough space to adequately describe ali three 
input fields on the same tutorial panel. 


e You want the tutorial panels to contain input fields so that input 
entered by the user can be transferred to the corresponding input 
fields on the action panels. 
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SHELP 


Step I: First, you create three tutorial panels — one for each input 
field on the action panel. 


Step 2: On each of the tutorial panels you define one input field and 
specify its label name to be the same as for the corresponding input 
field on the action panel. 


Step 3: You combine these three tutorials into one tutorial book. For 
more information, see “Tutorial Books” on page 49. 


Step 4: You display the action panel using SMOD. When an interrupt 
from your user occurs, you check if any of the three input fields has a 
question mark in it; if one does, you display the particular tutorial 
panel for the field that contains the question mark. You could do this 
in the following way: 


L:SMOD ‘ACTION! 
>(e'2te"VAR1 VAR2 VAR3)/L1,L2,L3 


SDTUT 'TUT01' 


As you see from the example, if a question mark is entered in field 
L1, the tutorial panel TUTO1 is displayed using the SDTUT function. 
Likewise, separate tutorial panels would be displayed if a question 
mark was entered in either field 2 or L3. 


After displaying one tutorial panel, the user can scroll to the other two 
tutorial panels by using PF keys. The user may enter data in the input 
fields on any of the tutorial panels, 


When the user leaves the tutorial book and returns to the action 
panel, any data entered in the input fields on the tutorial panels will 
now be dispiayed in the corresponding input fields on the action 
panel. 


Note: The user leaves tutorial mode by either pressing the END key 
(normally PF 3) or by entering data into one of the input fields on a 
tutorial panel and then pressing ENTER. The user is not required to 
enter data into the input fields on the tutorial panels before returning 
to the action panel. Furthermore, using the scrolling keys does not 
cause the user to leave the tutorial. 
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SHLT and SHLTI 


SHLT and SHLTI — Change Field Highlighting 


Purpose To change the field highlight attribute in the current panel. 


Syntax V SHLT H 
V SHLTI H 


H is a numeric vector containing field highlight attribute codes: 


0 Normal 2 


= Reverse Video 
1 = Blinking 4 


Unéerscored 


"n 


V isa label list. 
Example 'MEMBNO' SHLT 1 


Result The highlighting of ficld MEMBNO is set to blinking. 


Usage Notes 


Sets the highlight attributes for the specified fields to the values 
provided in the numeric vector H. 


SHLT changes the highlighting on the next update of the current 
panel; SHLTI changes the highlighting on the panel that is currently 
displayed. 


Note, For a description on how to change the highlighting of 
individual characters in a field, see . . AHI on page 81. 
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SINP 


SINP — Display Panel and Read Input 


Purpose 


Syntax 


Example 


Result 


To display and read input data from one or more panels. 
SINP P 

P isa panel list or an empty vector. 

SINP 'MINFO PANO1! 


Displays panel MIN FO and waits for user input; when the user presses ENTER or PF 8, 


the next panel (PAW 01) is displayed. 


Example SINP 


Result Displays current panel and waits for user input. 


Usage Notes 


SINP formats and writes the panel(s) to the screen, including the 
contents of any variables named for output fields on the panel(s). In 
addition, a chart function will be executed if one has been associated 
with the panel. Input fields are not updated from variables in the 
workspace; however, any default values for input fields that were set 
during design of the panel will be displayed. The user can then 
update the input fields. 


When displaying more than one panel, the scrol! PF keys (normally PF 
7 and PF 8) allow you to browse among the panels. You press the 
END key (normally PF 3) to end the display. Note, however, that the 
PF key information will not be displayed on the individual panels. 


Use SINP when your panel is, for example, a data input panel. No 
variable data is written to the input fields, which makes it somewhat 
faster than the SMOD function. All data entered into input fields 
during panel design is, however, written to the screen. You might 
want to use this to display your default values to the user of your 
panels without having explicitly to set all of them before displaying 
the panel in question. SINP will read in all the values for you; that is, 
it will set all the values displayed, whether the user modified your 
default values. or not. In such a case, initiating your variables and 
using SMOD would have the negative effect of increasing the 
processing time required. 


To improve performance, you can use SINP with an empty vector as 
aright argument, just as with SMOD. See Figure 17 on page 63, 
keeping in mind that STWP could be substituted in the example for 
SMOD. 
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SINT and SKCL 


SINT and SINTI — Change Field Intensity 


Purpose To change field intensity in the current panel. 
Syntax V SINT I 
V SINTI I 
I isa numeric vector containing field intensity codes: 
Invisible 
Normal Intensity 
Bright Intensity 
V isa label list. 
Example 'MPHONE' SINT 2 
Result Sets the field MPHONE to bright intensity. 
Usage Notes 


Sets the intensities for the specified fields to the values provided in 


the numeric vector T. 


SINT changes the field intensity at the next update of the current 
panel; SINTI changes the intensity immediately on the panel that is 


currently displayed. 


SKCL — Test CLEAR Key 


Purpose 


Syntax 


To determine if the CLEAR key was used. 
Z*SKCL 


Z returns | if the CLEAR key was used to terminate the last screen input and 0 


otherwise. 
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SKEN and SKPA and SKPF 


SKEN — Test ENTER Key 


Purpose To determine if the ENTER key was used. 
Syntax Z*SKEN 


Z returns 1 if the ENTER key was used to terminate the last screen input and 0 
otherwise. 


SKPA — Test PA Key 


Purpose To determine if a PA key was used. 
Syntax Z*SKPA 


Z returns the number of the PA key used to terminate the last screen input, if a PA key 
was used, and 0 otherwise. 


SKPF — Test PF Key 


Purpose To determine which PF key was last used. 
Syntax Z+SKPF 


Z returns the number of the PF key used to terminate the last screen input, if a PF key 
was used, and 0 otherwise. 
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SKPL and SLOADPS 


SKPL — Test Logical PF Key 


Purpose To determine which logical PF key was last used. 
Syntax Z+SKPL 
Z returns the number of the logical PF key which was used to terminate the last screen 
input, if a PF key was used, and 0 otherwise. 
Usage Notes 


give the same result. 


SLOADPS — Load Program Symbol Storage 


Purpose To load program symbol storage and reserve it for your own use so that GDDM will not 
use this storage. 
Syntax S SLOADPS F 
S isan integer scalar specifying a program symbol storage: 
1 = PSA 3 = PSC 5 = PSE 
2 = PSB 4 = PSD 6 = PSF 
F isa character vector naming an external symbol file (filetype ADMSYMBL), or, it is 
an empty vector. 
Example 3 SLOADPS 'MYSYMBOL' 
Result Program symbol storage PSC is loaded from MYSYMBOL. 
Usage Notes 


The specified symbol storage is loaded from the named symbol file. 


F is an empty vector, the PS storage is released to GDDM. 
SLOADPS must be executed before using SPSS and SPSSTI. 


Note: The symbol set is created using the Image Symbol Editor of 
GDOM (see GDDM Base: Image Symbol Editor User’s Guide). 
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SMOD 


SMOD — Display Panel with Data and Read Input 


Purpose To display one or more panels for automatic input and output of data. 


Syntax SMOD P 


td 


Example SMOD 


is a panel list or an empty vector. 


'MINFO' 


Result Displays panel MINFO and waits for user input. 


Exampe SMOD 


Result Displays the current panel and waits for user input. 


Usage Notes 


Using One Panel 


It is most usual that SMOD is used to display a single panel. 


SMOD formats the screen according to the specified panel. The 
variables named in the panel are written to the screen and any named 
chart function (one only) is executed. SMOD then awaits input from 
the user. If the user presses the HELP key, the current tutorial (if 
active) is entered. 


If an empty vector is specified instead of a panel name (that is, SMOD 
' +), the current panel is redisplayed without updating the data in the 
panel. Using SMOD in this way improves performance because data 
on the current screen is not updated. For example, on a panel with 
numerous fields where only one field is in error, better performance 
results would be achieved by using the SMSG function to display an 
error message and then redisplaying the panel using SMOD with an 
empty right argument. To update the field directly, you can use the 
following functions: SMSG, SWRI, SCOL, SHLT, SINT, STYP,or 
SERA. Before displaying the panel, you can further improve 
performance by using the SBMOD function to check which fields have 
been modified. 


The user terminates input, or any screen communication, by pressing 
an interrupt key. Later the application can investigate which key was 
used through the SKPA, SKPF, SKPL, SKCL, or SKEN 
functions. When the input is terminated, all modified input fields are 
read into the appropriate variables in the workspace. 
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SMOD 


Note: |f an attribute of i or S (a light pen field) was assigned to a 

field, a corresponding variable will not be updated in the workspace. 
The field, however, is marked as modified. This is the normal use of 
a light pen; for a description on how to determine if a field has been 
marked as modified, see SMODF on page 64 and SBMOD on page 9. 


You may set trailing blanks or nulls on your input fields by using the 
NULLS keyword of the A_S#T function. For more information, see 
“NULLS — NULLS Control” on page 205. 


You may also change the color, highlighting, or PS storage usage for 
individual characters on a panel. For more information, see pages 80 
through 83. 


Using More Than One Panel 


If the panel list contains more than one panel name, the user is 
allowed to scroll through the panels using the PF keys. For each 
panel in the list, SMOD will insert one or two lines at the bottom of the 
screen (if available), as follows: 


e The second-to-last line describes the PF key operations. 


è The last line contains page reference information, where you can 
enter a new page number. 


Using SMOD with more than one panel is intended for tutorial panel 
display, and recursive use of SMOQD is, incidentally, Application 
Prototype Environment’s own way of displaying tutorial books. 


Note: Under certain conditions, Application Prototype Environment 
needs to redisplay a panel, and therefore has an internal notation of 
which number in a sequence of numbers was last shown. This 
number is set at the end of browse mode and is used at the next 
browse panel display — if not indicated. The SHELP function is used 
to initiate a tutorial book at a specific page. For more information, see 
SHELP on page 48. If SHELP is not used, the tutorial book will be 
entered at the tutorial page that was last displayed, if that particular 
page is stiit available. 
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SMOD 


If you want to display two consecutive input panels before you 
process data, the following sequence provides much better control: 


[13] SMOD 'PANEL1' 
Č16J SMOD 'PANEL2' 


Example of Improving Performance 


The following example shows how to improve performance by using 
SMOD. In this example, there are five input fields (LAB1 — LABS) 
which must be checked after displaying the current panel (PNAME). 


In this exampte, modified input fields are tested and invalid input 
fields are automatically checked the next time the current panel is 
displayed. 
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SMO 


D 


E.J 

[21] LIST + A_BX 
C..] 

[25] LOC + 5p0 
fo.) 

C342 £1: SMOD '' 
C..) 


C..] 


Cel 
[51] +0K/L2 
(52) 
(53) 
Ezel 


C..3 


[71] +L4 
(72) L4: LOC[1]+0 
C..] 


[11] SDISP 'PNAME* 


'LAB1 LAB2 LAB3 LABY LABS' a Define label names 


[41] LOC + LOC v SBMOD LIST a Test if fields were modified 


C47) +(~LOC(1))/L3 


[55] 'A' SMSG 'Input xyz in error' 


[56] +41 

(57) 42: LOC[1]+0 a No error in 1st field, so set to 0 
[58] L3: *(~LOCC2I)/L5 a Test if 2nd input field modified 
t59) a Else, test next (L5) input field 
EFE] 

C67] +0K/L4 a If no error, go to Lu 

[68] a Else, redisplay current panel 
[69] a with error message 


[70] 'At SMSG 'Input xyz in error' 


Se | 


a Make PNAME current panel 


a Local variable for testing input 


a Display current panel (PNAME) 


a Test if first field modified 


a If no error, go to L2 
Else, redisplay current panel 
a with error message 


a No error in 1st field, so set to 0 


Figure 17. Example of Improving Performance Using SMOD 


If you specify data testing when you design a panel, the type of 
testing shown in Figure 17 is done automatically. Testing is 
optimized and your own coding is simplified. The code in Figure 17 
is reduced to a few lines in a test specification that you define when 
you design your panel, plus one tine in which SMOD is used to 
display the panel. 
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SMODF 


SMODF — Identify Modified Fields 


Purpose To find the names of fields which have been modified. 
Syntax Z<SMODF 


Z is a character matrix, containing (in each row of the matrix) the label of a field 
modified during the last input operation. 
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SMSG 


SMSG — Display Message 


Purpose To place a message on the screen. 


Syntax S SMSG M 


M 
sS 


Example '6Az' 


is the message (character string), 


is a control vector (character string), as follows (in any order): 


I 


A 
wW 
X 
Cc 


writes message immediately. 
sounds alarm. 

synchronizes with user. 
displays on the next panel. 
is a color code: 


Default 
Blue 

Red 

Pink 
Green 
Turquoise 
yellow 
Neutral 


NYOUBWNSO 
dea wie 


SMSG ‘Data must be numeric only 


Result Writes a message immediately, in yellow, and sets the alarm. 


Usage Notes 


The message is automatically placed in a field with a label name of 
MSG. Thus, you should define a field with this label name in panels 
where you intend to use SMSG, 


If a MSG field does not exist, however, one will be automatically 
added to the current panel when SMSG is used. The MSG field will 
remain a part of that panel only as long as it is the current panel. if 
no room is found for a MSG field on the current panel, some text in 
the panel will be temporarily overlaid by the message. When panet 
text is overlaid, the W option of SMSG is automatically used. 
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SMSG 


The following are some notes on the control options: 


ae 


Writes the message immediately. This works in the same way as 
the SWRIT function. 


Sounds the alarm. This works as if the SALE function had been 
used. 


Synchronizes with the user. When this option is specified the 
panel is displayed with all input fields temporarily protected. The 
standard message “Press ENTER to continue” is also shown; the 
user can then proceed as before, after pressing ENTER. 


Displays the message on the next panel. Normally, SMSG is 
used on the current panel. If SMSG is used and a new panel is 
made current, then the information from SMSG is normally 
cleared. With the X option, this information is not cleared; thus, 
the information from SMSG will still be displayed. This can be 
useful, for instance, when a lower-level function passes a 
message to a panel displayed by a higher-level function; and, the 
lower-level function is called between the execution of an 
SSAVE and an SREST function. For example, you might use 
the X option to display a message on a menu after returning 
from your application function (the MRUN function uses the 
SSAVE and SREST functions). 


Changes the color of the MSG field. 
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SNUMRC 


SNUMRC — Check Data Entered in Numeric Fields 


Purpose To check the return codes from data entered in numeric input fields on the current panel. 
Syntax 2+SNUMRC V 
V isa label list. 
Z contains a return code for each label: 
1 if the numeric data is invalid 
(0) in all other cases. 


Example SNUMRC 'MEMBNO' 
1 


Result Shows that the numeric data in the field MEMBNO is invalid. 


Usage Notes 
Z contains, for each label in the list, a return code indicating the 
result of a check on numeric input. 


1. When the NUMACCEPT keyword of the A_SET function is set to 
ON (or 1), which is the default, all numeric input is corrected and 
all return codes are set to 0. Correction of invalid numeric input is 
done by retaining the first valid number or sequence of numbers, 
and discarding the invalid part. If none of the input is valid, the 
input will be set to 0. This type of correction is shown in the 
following two examples: 


8£2 corrected to 8 
AB corrected to 0 


2. When NUMACCEPT is set to OFF (or 0), a return code of 0 is 
returned for each label with valid numeric input; the return code is 
1 if the input is invalid; no attempt is made to correct invalid input. 
To be valid, numeric input must conform to APL syntax. 
Examples of valid numeric input are: 


5 -333 ~.8 882 38-1 ~2E-4 


For a description of the VUMACCEPT keyword, see A_SET on page 
199. 
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SOUT 


SOUT — Display Panel and Protect Fields 


Purpose To display one or more panels, including automatic data output {no input data can be 
entered). 


Syntax SOUT P 


P 


is a panel list. 


Example SOUT 'MINFO' 


Result Displays panel MINFO with all fields protected. 


Usage Notes 


Use SOUT if you want to display a panel and the variables named in 
that panel only. SOUT does not try to read any data from the terminal, 
and is therefore somewhat faster than the SMOD function. 


The screen is formatted according to the specified panel. All fields in 
the panel will be protected regardless of the actual design of the 
panel. All variables named in the panel are written to the screen and 
any named chart function is executed. SOUT then awaits an action 
from the user. For more information, see SMOD on page 60. 
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SPRI 


SPRI — Create Panel Hardcopy 


Purpose To create a hardcopy of the current panel. 


Syntax SPRI 


Usage Notes 


The SPRI function creates a file containing a copy of the current 
panel, 


The actual destination of the copy is an ADMPRINT file, which can 
subsequently be printed by the GDDM output print utility. The name 
of the print file is specified by the COPY _ID function. If COPY _ID 
produces an * (asterisk), no output will be produced. 


If you wish, you may edit COPY _ID to change the name of the print 
file that is produced. See COPY _TD on page 6 for further details. 


Note: SPRI produces a graphical image that includes any charts 
displayed on the current panel. Note that you should use the A_DOC 
function to document a panel. 
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SPRIGRA 


SPRIGRA — Create Graphical Hardcopy 


Purpose To create a hardcopy of the graphics field on the current panel. 
Syntax SPRIGRA N 


N isan empty vector (provides default screen sizes); or, it is a two-element numeric 
vector: 


[1] number of rows (default is 55) 
[2] number of columns (default is 100). 


Usage Notes 
The current graphics field, as constructed by the graphics function, is 
copied to an ADMPRINT file. The filename of the print file is set with 
the COPY _ID function. You can alter the size of the hardcopy output 
with N. 


SPRIGRA copies only the graphical field, not the whole panel as with 
SPRI. The aspect ratio (ratio of rows to columns), which is 
maintained by SPRIGRA, determines the size of the printed result. 
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SPRIX 


SPRIX — Create Proportional Panel Hardcopy 


Purpose To create a proportional hardcopy of the current panel. 
Syntax [F] SPRIX N 


F (optional) is a filename. If not specified, the filename produced by the COPY_ID 
function will be used. 


N is a numeric vector of 3 clements: 
[1] row size (default: 66) 
[2] column size (default: 80) 
[3] number of copies (default: 1) 
or, it is an empty vector or zero, in which case the default values are used. 


It can also be a nine clement numeric vector that conforms to the syntax for the 
FSOPEN command of GDDM. For more information on the FSOPEN command, 
see Graphical Data Display Manager Base: Programming Reference. 


Example 'PANFILE' SPRIX 50 80 2 


Result Creates a print file, called PAN FILE, containing an image of the current panel. Two 
copies containing 50 rows and 80 columns will be printed. 


Usage Notes 
The entire current panel is converted to a graphics image and then 
copied to an ADMPRINT file. Both graphics and alphanumeric fields 
are printed using the GDDM symbol sets. You can alter the size of 
the output by specifying row and column numbers in the argument N. 
Whatever size you specify, the aspect ratio will be preserved. If you 
specify an empty vector, the defauit size is used for the print file. You 
also have the option of specifying, in the third element of N, the 
number of copies to be printed. 


Note: The default symbol sets used by SPRIX are APL2!SSC and 
ADMDVSS. If these are not found, the GDDM default symbol sets are 
used. If you want to specify your own symbol sets, you can use the 
SPRIX keyword of the A_SET function. For more information, see 
A_SET on page 199. 
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SPSS and SPSSI 


SPSS and SPSSI — Specify Symbol Set 


Purpose To use a specific Program Symbol Set in the current panel. 
Syntax V SPSS S 
V SPSSI S 
S isan integer scalar (in the range 1-6) specifying a symbol set loaded by SLOADPS, or 
0 to reset usage of the symbol set: 
1 = PSA 3 = PSC 5 = PSE 
2 = PSB 4 = PSD 6 = PSF 
V isa label list. 
Example 1 SPSS 'MYSYMBOL' 
Result Uses symbol set PSA for field MYSYMBOL. 
Usage Notes 


Sets symbol set S for fields specified in V. 


SPSS changes the program symbol storage on the next update of the 
current screen; SPSSJ changes the program symbol storage 
immediately on the panel that is currently displayed. 


SLOADPS must have been executed prior to using the symbol sets in 
a panel. However, SLOADPS need only be used once for every 
Application Prototype Environment session. 
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SQCUR 


SQCUR — Query Cursor Position 


Purpose To determine where the cursor is positioned in specified fields. 
Syntax Z2«SQCUR V 
V isa label list. 


Z isa two-column, numeric matrix, containing one row for each of the fields specified, 
with the cursor position (row, column) noted in the first and second column. 


Example SQCUR 'MPHASE' 
3.5 


Result Retums the the position of the cursor in the field MPHA SE. 


Usage Notes 


Rows corresponding to fields not pointed to by the cursor contain 
zeros. 


For example, suppose that Vis 'LAB1 LAB2 LAB3' andthe 
cursor is in row 2 and column 5 of field LAB3; then Z is: 
00 
00 
25 


A result of 0 0 is returned for invalid or nonexistent labels. 
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SRESET and SREST 


SRESET — Reset Field Attributes 


Purpose To reset field attributes. 
Syntax SRESET V 

V isa label list. 
Example SRESET 'MPHASE' 


Result Resets field attribute of MPHASE to its orginal definition, as specified in PDESTGN. 


Usage Notes 
The attributes of the specified fields are reset to their originat 
definition. 


SREST — Restore a Panel 


Purpose To restore a panel level saved with SSAVE. 
Syntax SREST I 

I isa character vector containing an identifier for the level to be restored. 
Example SREST 'MYSAVE' 


Result Restores panel MY SAVE previously saved with SSAVE. 


Restores a panel level saved with SSAVE. The application state is as 
if no interruption had occurred between the SSAVE and SREST 
functions. 
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SSAVE 


SSAVE — Save Current Panel 


Purpose To save the contents and status of the current panel. 
Syntax SSAVE I 

I isa character vector containing an identifier for a saved level. 
Example SSAVE 'MYSAVE' 


Result Saves characteristics of the current panel in character vector MY SAVE. 


Usage Notes 
Saves the current panel with ail information on cursor placement, 
modified fields, and contents under the specified identifier. 


You can improve performance by saving the image before displaying 
another panel, and then using SREST when you wish to redisplay 
the saved panel. 


All data pertaining to the current panel is saved in a variable with the 
name of the save level, prefixed with S_. This variable is expunged in 
SREST. \f you repeatedly use one and the same SSAVE name (for 
example, in a chain of recursive calls), you might want to localize this 
variable to protect the higher save level. 
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STYP and STYPI 


STYP and STYPI — Change Field Type 


Purpose To change field types in current panel. 
Syntax V STYP T 
V STYPI T 
T isa numere vector containing field type codes: 
0 = Alphanumeric input 
1 = Numeric input 
2 = Output field 
3 = Immediate pen selectable 
4 = Deferred pen selectable 
5 = Pen enterable. 
V isa label list. 
Example 'INPUT' STYP 1 
Result Changes field type of field INPUT to numeric input. 
Usage Notes 


Sets the field types for the specified fields to the values provided in 
the numeric vector T. 


STYP changes the field type on the next update of the current panel; 
STYPI changes the field type immediately on the panel that is 
currently displayed. 


Note: STYP and STYPI cannot be used to change to and from a 
graphics field, 
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SWRI and SWRIT 


SWRI and SWRII — Write Data to Panel Fields 


Purpose To place data explicitly in fields in current panel. 


Syntax V SWRI M 
V SWRIIT M 


M isa character vector (for one field) or a matrix with a row for each field specified in V. 
V isa Jabel list. 
Example 'MPHASE' SWRI 'Member Verification' 


Result Writes the specified text to the field MPHASE on the current panel. 


Usage Notes 
Writes the contents of to the fields specified in V. 


SWRI writes data to the screen on the next update of the current 
panel; SWRIT writes data immediately to the panel that is currently 
displayed. 


If you use SWRI to update a field, and a variable exists in the 
workspace with the same name as the field label, you will not see any 
change as a result of the SWRI operation. This is because the SWRI 
update is done before the field is updated by the variable. 


One use of the SWRIT function is to write a message that informs the 
user about the processing status for functions that take a long time to 
execute. Examples of this usage of SWRIJ can be seen when you 
use the DOCUMENT function. 
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Purpose To determine cursor position in a graphic field. 
Syntax Z + GCUR 


Z is a two-element vector with the window coordinates for the cursor, if this was 
positioned in a graphics ficld at the last input; otherwise 0 0. 


Usage Notes 
For information on window coordinates in GDDM, see GDDM Base: 
Programming Reference. 


HELP — Protect Tutorial Stack 


Purpose To protect the tutorial stack. 
Syntax HELP 


The HELP default value is empty. 


Example VMYFUNC RA;A;B;HELP 


C 
Result Localizes HELP to MY FUNC. 


Usage Notes 
This variable is set by the SHELP function and used by the system to 
determine the next tutorial to be used. 


You may use HELP to localize the tutorial stack. If you do so, you do 
not need to reset the stack when you leave a function — a higher-level 
tutorial stack is automatically reinstated. For more information, see 
SHELP on page 48. 


Do not assign values to HELP; use SHELP instead. 
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Purpose To specify the functions of PF keys. 


Syntax PREKEY 


Example PFKEY[1 3] + 3 1 


Result The operations of the PF ł and PF 3 keys are switched; PF } is now the END key, and PF 
3 is the HELP key. 


Usage Notes 


Each element assigned to PFXEY defines the function of the 
corresponding PF key by assigning a command number to the 
element. 


Setting Program Function Keys 


All usage of PF keys in Application Prototype Environment reflects the 
setting of PFKEY. Thus, if you switch the PF 1 and PF 3 keys so that 
PF 1 is defined with the END operation and PF 3 is assigned the HELP 
operation, the PF keys shown on the panels in the product will be 
changed accordingly. The manuals and tutorials of course describe 
the PF key usage according to the default values. 


Do not become confused by the fact that the default command number 
happens to correspond to the default PF key number. If, for example, 
you change the starting sequence to look like: 


B28 BG bs 


then you will switch the use of PF 1 and PF 3. PF 1 is now your END 
key, and PF 3 will be your HELP key. 


You may allow users of your application to change the setting of 

you use SKPL instead of SKPF to check for PF key usage. SKPF 
returns the actual PF key used, whereas SKPL returns the “logical” 
key used. Thus, SKPZ will always return 3 for the END operation 
regardless of the key actually pressed. 
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«ACA 


This variable is a numeric vector of length 24. Each element assigns 
a command to the PF key with the same number as the index of the 
element within PFKEY. Thus the command number entered as the 
first element of PFKEY is the command assigned to PF 1. The default 
setting of PFKEY is: 


position. If no available positions are found, PF 3 will be changed to 
the END command. 


System usage of the PF keys is always displayed on the bottom of the 
panels (with the exception of a few panels in PDESIGN). The PF key 


- . ACA — Change Color of Characters 


Purpose To change the color of individual characters in a field. 


Syntax variableA CA 


Usage Notes 


For screen handling you may specify color at an element level. The 
character-color attributes for a variable are contained in a variable 
having the same name, with ACA added as suffix. The valid 
character-color attributes are the color numbers, provided as single 
characters. The valid character-color attributes are: 


0 = Default 4 = Green 

1 = Blue 5 = Turquoise 
2 = Red 6 = Yellow 

3 = Pink 7 = Neutral 
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<.. AHI 


An example of changing colors at the element level is shown in 
Figure 18. 


Starting with: 
VARA + 123.34 345,34 456.44 
VARB + *ABCDEFG* 
and 
VARASCA + * 24! a (2=Red, 4=Green) 
VARBSCA + ' 6 6 7 ' a (6=Yellow, 7=White) 


When the variables VARA and VARB are used in a panel, they are displayed as: 


VARA VARB 
+ + +- 

{ 123.341 LABCDEFG i 
{ 345.341 (red) Entenet 
| 456.44] (green) 
+ + 


Figure 18. Using Character-Color Attributes 


Usage Notes 
Any character position that does not contain one of the valid color 
codes will be displayed in the field’s own color — which is either the 
color defined in PDESIGN or the color set by the SCOL function. 


. -AHT — Change Highlighting of Characters 


Purpose To change the highlighting of individual characters in a field. 


Syntax variableA HI 


Usage Notes 
For screen handling you may specify highlighting at an etement level. 
The character-highlighting attributes for a variable are contained in a 
variable having the same name, with AHT added as suffix. The valid 
character-highlighting attributes are: 


0 = normal 2 = reverse video 
1 = blinking 4 = underscored 
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An example of changing highlighting at the element level is shown in 


Figure 19. 


Starting with; 
VARA + 123.34 345.34 456.44 
VARB + 'ABCDEFC' 

and 
VARAGHI + 'h 4! 
VARBAHI + '2 2 


a (4=underscored) 
2' a (2=reverse video) 


When the variables VARA and VARB are used in a panel, they are displayed as: 


VARA VARB 
fenseecee + foccee eens + 
| 123.341 (underscored) |ABCDEFG | 
1 345.341 4-2-2- + 
1 456.441 (underscored) | 
at + +---- reverse video 
Figure 19. Using Highlighting Attributes 


Usage Notes 


Any character position that does not contain one of the valid 
highlighting codes will be displayed in the field’s own highlighting — 
which is either the highlighting defined in PDESIGN or the 
highlighting set by the SHLT function. 
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--APS 


. e APS — Change Symbol Set for Characters 


Purpose To change Program Symbol Set usage for individual characters in a field. 


Syntax variableA PS 


For screen handling you may specify Program Symbo} Set usage at 
the element level. The symbol set attributes for a variable are 
contained in a variable having the same name, with AHI added as 
suffix. The valid symbol sets are: 


1 
2 


PSE 
PSF 


PSA 3 = PSC 5 
PS3 4 = PSD 6 


An example of changing program symbol set usage at the element 
level is shown in Figure 20. 


Starting with: 
VARA + 123,34 345.34 456,44 
VARB + 'ABCDEFC' 
and 
VARAAPS + * 42' a (4=PSD, 2=PSB) 
VARBAPS + '3 3 37 a (2=PSB) 


When the variables VARA and VARB are used in a panel, they are displayed as: 


1 123.341 
( 345,34] (PSD) 
1 456.44| (PSB) 


Figure 20. Using Program Symbol Set Attributes 


Usage Notes 
Any character position that does not contain one of the valid symbol 
set codes will be displayed with the field’s own symbol set — which is 
set using the SLOADPS and SPSS functions. 
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Chapter 3. Chart Functions 


A chart function is an APL function containing the code needed to 
display a chart. When you create a chart using Chart Design 
(CDESIGN), a chart function is automatically created for you. 
CDESIGN produces the following two objects when you create a 
chart: 


1. A graphical function. 


2. A variable containing chart parameters that are used for 
redesigning charts. 


You may edit and modify the graphical function produced by 
CDESTGN. lf you edit the graphical function and then again specify 
the same chart name in CDESIGH, your modifications will be lost. 
You should rename the function because, at the end of CDESIGN, a 
new function with the same name is established. To avoid this type of 
name conflict, you can save your graphical function under a different 
name. 


Note: To design and operate chart functions, the Presentation 
Graphics Feature (PGF) of GDDM is required. Also note that 
Application Prototype Environment does not check whether vatid 
attributes are specified for the PGF functions. 


For more information on designing charts, refer to Application 
Prototype Environment: Guide. 
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CAND and CDESIGN and CHAFNS 


CAND — Create Dependent Variables 


Purpose To join vectors or matrices as dependent variables. 
Syntax Z+A CAND B 
A B are vectors or matrices. 


Z is a vector or matrix containing the join of A and B. 


Usage Notes 
Joins the vectors or matrixes in A and B as dependent variables for a 
chart. The arguments must have an equal number of elements or 
rows. In a matrix each column will represent a dependent variable. 


CDESIGN — Call the Chart Design Menu 


Purpose To call the Chart Design (CDESI CN) menu. 
Syntax CDESIGN 


Usage Notes 
Displays a menu containing options for designing charts. 


CHAFNS — Show Chart-Handling Functions 


Purpose To display a list of the available chart-handling functions. 


Syntax CHAFNS 


Usage Notes 
The list includes a short description of each of the chart-handling 
functions. For more information, use the SHOW command or the PF 10 
key against any of the functions in the list. 
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CHARTOUT 


CHARTOUT — Display a Chart 


Purpose To display the current panel or chart. 
Syntax CHARTOUT 


Usage Notes 
Normally, a chart is displayed in a panel where a graphical field has 
the same name as the graphical function. The chart is then displayed 
when the panel is displayed. 


You might, however, want to display the chart by itself, without being 
connected to a panel. You could do the following: 


1. If necessary, first clear the screen with the SCLEAR function. 
2. Next, execute the chart function. A panel is automatically created 
and made current for you; this panel has a graphical field that 


covers the entire screen. 


3. Finally, issue the CHARTOUT function to display your chart on the 
screen. 
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CHARTSETUP and CLIST 


CHARTSETUP — Prepare a Chart for Display 


Purpose To prepare a graphical field, in a panel or on the entire screen, for graphical output. 


Syntax CHARTSETUP 


Usage Notes 


If the current panel that is to be displayed contains a graphics field, 
that graphical field will be cleared and subsequent calls to the PGF 

support functions will create a chart in the field. If the current panel 
does not contain a graphics field, an error message is issued. 


If no panel is current, CHARTSETUP creates a current panel with a 
graphics field covering the entire screen, and subsequent calls to the 
PGF support functions will create a chart covering the screen. (You 
can ensure that no panel is current by first issuing the SCLEAR 
function; see SCLEAR on page 38 for more information.) 


The CHARTSETUP function is automatically included in the chart 
function produced by CDESIGN. Thus, the only time you might need 
to know about CHARTSETUP is if you decide to modify the graphical 
function produced by CDESIGN. 


CLIST — Display List of Charts 


Purpose To show a list of all user-created charts. 


Syntax CLIST 


Usage Notes 
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You can use commands and PF keys to perform operations on the 
charts in the list. Press PF 1 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 


Vs 


VS — Create Independent Variables 


Purpose 


Syntax 


Example 


Result 


To set numeric vectors as independent variables. 


Z+Y VS X 


x is a numenic vector representing the independent variable. 


Y is the dependent variable. 


CHSURF Y1 CAND Y2 VS X1 


Creates a surface chart of Y 1 and Y2 as dependent variables and X1 as the independent 


variable. 


Other Graphical Functions 


PGF Cover Functions 


When you use CDESIGN to build your graphical function, a valid 
combination of PGF cover functions will be built automatically for you. 
If you are satisfied with the provided combination, you do not need to 
use the functions shown in Figure 21. 


However, if you want to modify the combination built by CDESTGN, or 
completely construct your own combination, then you need to know 
about PGF’s states and other details about how PGF works. This 
information is provided in GDDM PGF: Programming Reference. 


After CHARTSETUP, PGF is in state 1, and state 1 macros can be 
used until PGF transits to state 2. The state in which a specific macro 
is allowed is marked with Y (yes) and functions making transition 
between states are marked in the table with an arrow (+ or +). 


Application Prototype Environment contains a set of PGF Support 
functions for the calls to GDDM/PGF. Figure 21 shows the PGF 
functions for which cover functions are available, with a note on the 
usage for each one. 


State 
Call Description 1 2 
CHAATT Axis line attributes Y 
CHAREA Chart area Y 
CHBAR Bar charts Y > ¥ 
CHBATT Set framing box attributes x 
CHCGRD Basic character spacing/size Y 
CHCOL Component color table y 
CHDATT Datum line attributes ¥: Y 
CHDRAX Specific control of axis drawing Y 
CHFINE Curve fitting smoothness X Y 
CHGAP Spacing between bars Y: Y 
CHGATT Grid line attributes Y 
CHGGAP Spacing between bar groups y Y 
CHHATT Heading text attributes Y 
CHHEAD Heading text ti 
CHHIST Histograms Yry 
CHHMAR Chart margin specifications ¥ 
CHKATT Legend text attributes Y: 
CHKEY Legend key labels Y 
CHKEYP Legend base position Y 


Figure 21 (Part L of 2). Available PGF Cover Functions 
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State 

Call Description 1 2 
CHKMAX Maximum legend width/height Y 
CHKOFF Legend offsets Y 
CHLATT Axis label text attributes Y 

CHLT Component line type tABLE Y 
CHMARK Component marker table Y 
CHNATT Specify text attributes for notes Y Y. 
CHNOFF Specify offset for CHNOTE Y Y 
CHNOTE Construct a chart note Y 
CIINUM Set number of components Y 
CHPAT Component shading pattem table Y 

CHPIE Pie charts Y > Y 
CHPIER Size specification Y 
CHPLOT Line graph and scatter plots Yo se _¥Y: 
CHRNIT Reinitiate PG routine Yo E i 
CHSET Specify chart options 

CHSTRT Reset to state | (retain settings) l AE a d 
CHSURF Surface charts YY 
CHTATYT Axis title text attributes Y 
CHTERM Terminating the process Y Y 
CHVATT Attribute values text in bar and pie Y +- Y 
CHVCHR Number of bar value characters x Y. 
CHVENN Venn diagram Y 
CHYMAR Chart margin specifications ha 
CHXDAY Day labels Y 
CHYDAY Day labels Y 
CHYRNG Explicit ranges Y 
CHXDTM Specify datum lines Y Y 
CHYDTM Specify datum lines Y ¥: 
CHXINT Specify intercept Y 
CHYINT Specify intercept Y 
CHXLAB Label text Y 
CHYLAB Label text Y: 
CHXMTH Month labels Y 
CHYMTH Month labels X 
CHXRNG Explicit ranges Y 
CHXSCL Scale factor Y 
CITYSCL Scale factor Y 
CHXSEL Axis selection Y Y 
CHYSEL Axis selection Y Y 
CHXSET Specify axis option Y 
CHYSET Specify axis option Y 
CHXTIC Scale mark interval Y 
CHYTIC Scale mark interval Y 
CHXTTL Axix title text specification Y 
CHYTTL Axix title text specification Y 


Figure 21 (Part 2 of 2). Available PGF Cover Functions 


The PGF Support functions have the same specifications as described 
in GDDM PGF: Programming Reference. For cases where GDDM/PGF 
expects the user to specify lengths or other numeric values, the 
following examples illustrate the correct syntax for Application 
Prototype Environment chart cover functions. 
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1. Standard PGF: 


CALL CHHEAD(13, ‘Sample Header’) 
2. Application Prototype Environment: 
CHHEAD ‘Sample Header' 


Further, when a varying number of entries are allowed, these are set 
as rows in a matrix for calling the cover functions. 


1. Standard PGF: 


CALL CHKEY(3,6, ‘Item AItem BItem C')2 
2. Application Prototype Environment: 
CHKEY 3 6p ‘Item AItem BiItem C' 


3. Standard PGF: 


PATRS(1)=3; PATRS(2)=4; CALL CHPAT(2,PATRS) ; 
4. Application Prototype Environment: 
CHPAT 3 4 
Before using the PGF Support functions, the interface must be 


initialized using, for example, the CHARTSETUP, and the chart will 
then be generated in the graphics field on the current panel. 


Chapter 4. File-Handling Functions 


This chapter contains a description of all file handling cover functions. 
For further information on the various file characteristics and access 
methods that you can use, see the Application Prototype Environment: 
Guide. 


Definitions 


Filename A filename is a character vector containing the name of a 
file or the alternate access path to that file. 


Declaration A declaration (created with FDESIGN) is a description 
of the record tayout and access method to be used. 


File Handling — Controlling Access 


The right-hand argument for all the file handling functions below is F, 

a character vector containing the name of the declaration. This name 
must be the same as the name for the physical file. For keyed access 
(INSTOR or VSAM), you may use any of the access paths specified in 

the declaration. 


CMS. in addition to specifying a filename for F, you can also 
specify a filetype and a filemode. 


F + 'filename filetype filemode' 


Assigning these three values to F automatically sets the ETZ 
variable. For example: 


FREAD ‘SALARY DATA A‘ 
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TSO 


a complete name can also be specified for F: 
F + 'filename.levelname' 
For example: 


FWRITE 'SALARY.DATA' 
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Summary of File-Handling Functions and Access Methods 


The following figure summarizes the relationship of file-handling 
functions to the various access methods. 


Functions Access Methods 


APE CMS QSAM VSAM BDAM DUMMY INSTOR 


FCLOSE * * + ‘ * + * 
FDROP * * * * 
FDUPK * . 
FEOF (9) * * * * * = $ 
PERASE (6) * * . 
PERR * * x * * * + 
FGET (3) * * * "e , ý 
FGETHOLD (4) » * * * $ * 
FILESIZE * * 

FKNOTF * * 
FLKEY * * 
FPOSITION (7) * * + * * * 
FREAD (1) * * + . * * * 
FREADHOLD (2) * * * * * * 
FRECS * * 
FSET (5) * * * * * 
FWRITE (8) * * . * * * * 
INSTORDSP * 
ET * * * 

INSS * 
PCODES * * * * * * * 
RCODE * * * * * * * 


+ Function can be used with indicated access method. 
Notes: 


(1). Sequential read 

(2) Sequential read, and place HOLD on file 

(3) Select and read record 

(4) Select and read record, and płace HOLD on file 

(5) Write a record, at position indicated by FREADHOLD or FGETHOLD 
(6) Erase record pointed to by key 

(7) Point to record to be read using FCET or PGETHOLD 

(8) Sequential write 

(9) Check for end-of-file in sequential read 


Figure 22.  File-Handling Functions and Access Methods 
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DLIST 


DLIST — Display List of File Declarations 


Purpose To display a list of all user-created file declarations. 


Syntax DLIST 


Usage Notes 
You can use commands and PF keys to perform operations on the 
declarations in the list. Press PF 1 from the list to display the 
available commands. You can display additional information about the 
commands by pressing PF 1 a second time. 
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FCLOSE and FDROP 


FCLOSE — Close File or Access Path 


Purpose To close a specified file and expunge variables. 
Syntax FCLOSE F 
F isa filename. 


Access Supports all access methods. 


FDROP — Delete a File 


Purpose To erase a file from the system. 
Syntax FDROP F 
F isa filename. 


Access Supports CMS, APL, DUMMY, and INSTOR access methods. 


Usage Notes 


The file F is erased from the system if the user is authorized to 
perform such an operation. 


F is either a single filename or a list of paths separated by blanks, 
commas, or slashes. The specified file or paths are closed. All 
associated variables are expunged, except those named in an index 
expression. 
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FDUMMYOPT 


F DUMMY OPT — Specify Data for Dummy Files 


Purpose ‘To specify the type of input data for a dummy file. 


Syntax FDUMMYOPT 


Usage Notes 
You are prompted for the following specifications: 


1. Maximum number of digits. 

The maximum number of digits returned for any type of numeric data. 
The variables will contain as many digits as the corresponding field 
can hold, limited by this maximum number. 


2. Random digits. 


Specify ‘Yes’ to generate random numbers or ‘No’ for a fixed number 
for all types of numeric data. 


3. Alphanumeric character. 

You can specify the character you want returned in variables when 
reading character data. A character variable will always have as 
many characters as the size of the corresponding field. 

The DUMMY filetype is specified using FDESIGN. 

The input data, as defined above, is automatically generated. Note 


that no output file is created, since output data is ignored (however, 
the file handling functions work normally). 
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FDUPK and FEOF 


FDUPK — Determine if Duplicate Key Used 


Purpose 


Syntax 


Access 


To determine if you attempted to enter data with a key that already exists. 
B+FDUPK 
B is 1 if the last operation specified a DUPlicate Key and 0 otherwise. 


The VSAM and INSTOR access methods are supported. 


FEOF — Check for End-of-File 


Purpose To determine if end-of-file has been reached. 
Syntax B+FEOF 
B is 1 if the last operation resulted in End-Of-File and 0 otherwise. 
Access All access methods supported. 
Usage Notes 


End-of-file cannot be reached in DUMMY files. 
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FERASE and FERR 


FERASE — Erase a Record from a File 


Purpose To erase a record from a key sequenced data set. 
Syntax FERASE F 
F isa filename. 


Access Supports VSAM, DUMMY, and INSTOR access methods. 


Usage Notes 


The file is opened for writing (if not already opened for writing) and 
the selected record is erased. The key is constructed based on the 
declaration of the file. 


FERR — Check Result of Operation 


Purpose To determine the outcome of the last I/O operation. 
Syntax B«FERR 
B is | if the last file I/O operation resulted in any error condition and 0 otherwise. 


Access Supports all access methods. 


Usage Notes 
If the value is 1, no actuat data transfer between the file and the 
variables in the workspace took place. The functions described below 
can be used to test for specific conditions. 
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FGET and FGETHOLD 


FGET — Read a Record (Relative Record/Keyed) 


Purpose To read a record selected by key or relative record number. 


Syntax FCET F 
F 


is a filename. 


Access Supports all access methods except QSAM. 


Usage Notes 


For files that can be retrieved by sequence key or relative record 
number. The key is constructed based on information in the 
declaration of the file. The indicated file is opened for reading (if not 
already open) and a record is read. If any record is retrieved it is 
split into variables according to the file declaration. 


FGETHOLD — Read a Record (Relative Record/Keyed) with HOLD 


Purpose Same as for FGET, except that a HOLD is placed on the file. 
Syntax FCETHOLD F 


F 


is a filename. 


Access Supports all access methods except QSAM. 


Usage Notes 


Same effect as for FGET, except that the file is opened for update and 
a HOLD is placed on the file. The file can be used in multiple-user 
applications only if allowed by the host system. The hold is released 
at the next read or write operation or by closing the file. 

FGETHOLD is used together with FSET to update existing records 
in a file. 
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FDESIGN and FILEFNS 


FDESIGN — Call the File Design Menu 


Purpose To call the File Design (PDESIGN) menu. 


Syntax FDESIGN 


Usage Notes 
Displays a menu containing options for designing file dectarations. 


FILEFNS — Display List of File-Handling Functions 


Purpose To display a list of the available file-handling functions. 
Syntax FILEFNS 


Usage Notes 
The list includes a short description of each file-handling function. For 
more information, use the SHOW command or the PF 10 key against 
any of the functions in the list. 
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PILESIZE 


FILESIZE — Specify Size of APL or BDAM Files 


Purpose To specify or respecify the size of APL or BDAM files. 


Syntax S FILESIZE F 


F 
S 


is a filename. 


is a numeric scalar. 


Access Supports API, and BDAM access methods. 


Usage Notes 


APL files: The size of the file F is (re)specified to be the number of 
bytes specified in S$. § is rounded up to the nearest multiple of 
4077. For example, if S is specified as 10,000, the total size of the file 
will be 12,231 bytes. The default size for APL files (that is, if 
FILESIZE is not specified) is 32K bytes. 


Note: |f the file does not exist, it will be created — unless PCODES 
contains a return code of 26 (“file not found”). 

BDAM files: This function can also be used to initialize BDAM files 
under TSO. You must initialize a BDAM file before using it, otherwise 
you will get errors. The initiatization process writes a certain number 
of “filler” records to the file. With FILESIZE, you specify how many 
records you want to write, and what they contain (filler data). 


S is the number of records you want to initialize. The minimum 
number of records is 10. If you specify a value of § less than 10, then 
10 records will be initialized anyway. 


If you want to specify your own filler data, then you must assign this 
data to the file’s variables (as specified in FDESIGN) before using 
FILESIZE. Ifa variable does not exist, it will be set to blanks in 
each initialized record. 


You can also use FILESIZE to reinitialize a BDAM file with new 
filler data, or a new number or records. Reinitializing a BDAM file 
means that the previous data will be Jost. 


Note: Creating a TSO file with FILESIZE will result in a file of the 
type ‘AAA.BBB.CCC’, where AAA is either the user ID or the value 
found in the Q L variable, and BBB and CCC could be values 
from the right-hand argument. This is shown in the foilowing 
example: 
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FKNOTF and FLKEY 


OLEVEL+' CATX' 


500 FILESIZE ‘NEW.DATA' 


In this example, a data set of 500 records with the name 
CATX.NEW.DATA’ will be created. 


FKNOTF — Determine if a Key is Found 


Purpose To determine if a key is found in a data set. 
Syntax. BeFKNOTF 
B is a numeric scalar containing } or 0. 


Access The VSAM and INSTOR access methods are supported. 


Usage Notes 
Returns 1 if the Key was NOT Found during retrieve or positioning for 
a key sequenced dataset and 0 otherwise. 


FLKEY — Determine Value of Last Key 


Purpose To determine the value of the last key used. 
Syntax Z«FLKEY F 

F isa filename. 

Z işa character vector. 


Access Supports the VSAM access method. 


Usage Notes 
Z contains the value of the last key used in F (for access methods 
where such a request is meaningful). 
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FPOSITION and FREAD 


FPOSITION — Position Next Record Pointer 


Purpose To position the next record pointer in a key-sequenced data set. 


Syntax FPOSITION F 


F 


is a filename. 


Access Supports all access methods except QSAM. 


Usage Notes 


The file is opened for reading (if not already opened for read or 
update). The key is constructed based on the declaration of the file. 
If any record matches the key provided, that record will be the next 
retrieved by FREAD or FREADHOLD. If there is no exact match, the 
next retrieved record wili be the one with the next higher valued key. 


FREAD — Read Next Record in a Sequential File 


Purpose To read the next sequential record. 


Syntax FREAD F 


F 


is a filename. 


Access Supports all access methods. 


Usage Notes 


The indicated file is opened for reading {if not already open) and the 
next sequential record is read. If any record is retrieved, it is split 
into variables according to the file declaration. The next record 
pointer can be changed by the FPOSITION, FGET, 
FGETHOLD, FERASE, and FSET functions. 
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FREADHOLD and FRECS 


FREADHOLD — Read Next Record (with HOLD) in a Sequential File 


Purpose To read the next sequential record and place a HOLD on the file. 
Syntax FREADHOLD F 
F isa filename. 


Access Supports all access methods except QSAM. 


Usage Notes 


Same effect as for FREAD, except that the file is opened for update 
and a HOLO is placed on the file. The file can be used in 
multiple-user applications only if allowed by the host system. The 
hold is released at the next read or write operation or by closing the 
file. FREADHOLD is used together with FSET to update existing 
records in a file. 


FRECS — Query Size of a File 


Purpose To query the size of a file. 
Syntax Z*FRECS F 
F isa filename. 
Z is a numeric scalar containing the number of records in file. 


Access Supports the CMS and INSTOR access methods. 


Usage Notes 
If the file does not exist, Z will contain 0. 
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FSET and FWRITE 


FSET — Add or Replace a Record 


Purpose To add or replace a record in an existing data set. 
Syntax FSET F 
F isa filename. 


Access Supports all access methods except QSAM. 


Usage Notes 
The record is constructed according to the declaration for the 
specified file. The file is opened for writing (if not already opened for 
write or update). If the previous operation was FREADHOLD or 
FGETHOLD of the same record, identified through the key or relative 
position, it is now replaced in the data set. If the constructed record 
is new, it is added either at the end or in key sequence, according to 
the organization of the data set. 


FWRITE — Add a Record 


Purpose To add records to a sequential data set. 
Syntax FWRITE F 
P isa filename. 


Access Supports all access methods. 


Usage Notes 
The file is opened for sequential write (if not already opened for 
write), and the record constructed according to the declaration for the 
file is added at the end of the data set. 
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INSTORDSP and FT 


INSTORDSP — Browse Instorage File 


Purpose To browse instorage files on the display screen. 
Syntax INSTORDSP F 
F isa character vector containing a filename. 


Access Supports only the INSTOR access method. 


Usage Notes 
Displays the file on a panel, with column headings as defined in the 
FDESIGN function. You can browse the file vertically and 
horizontally. 


ET — Specify Filenames 


Purpose To specify the filetype and filemode for a CMS file; or, the third level qualifier for BDAM 
and QSAM files. 


Syntax Erc 
C isa one- or two-clement character vector: 
[1] CMS filetype; or, TSO third level qualifier. 
C2] file mode (CMS only). 


Access Supports the CMS, BDAM, and QSAM access methods. 


Usage Notes 
CMS C contains the filetype and possibly the filemode for the file. If 


not set to a value, the filetype and filemode will be set to 
'VMAPLYF A’. 


TSO C contains the third level qualifier for BDAM and QSAM files. 


For more information, see the description under “File Handling — 
Controlling Access” on page 93. 
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Syntax 


Access 


— Specify Collating Sequence 


To specify the collating sequence used in sorting keys on instorage files. 
LNSS*C 


C isa character vector containing the alphanumeric sorting sequence for key sequential 
access to instorage files. 


Supports only the INSTOR access method. 


Usage Notes 


lf INSS is not used, that is, if it is not present in the workspace, a 
system default sorting sequence will be used instead. 


Purpose To define access return codes that the user wants to handle. 
Syntax = PCODES+V 
V isa numeric vector containing the return codes the application will itself handle by 
special programming. 
Access All access methods are supported. 
Usage Notes 


inserting values for access methods that use both return and reason 
codes (for example, VSAM access using the APL auxiliary processor 
AP 123), combine these into one number using the expression: 


PCQDES + PCODES , 100000: RETURNACODE,REASONACODE 
The file handling functions wil! always trap the end-of-file (FEOF), key 
not found (FXNOZF), and duplicate key (FDUPK) return and reason 
codes. 
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Access All access methods supported. 


Usage Notes 


This variable contains the return code from a file-handling function. 
The errors described below are always trapped by the file-handling 
functions and will be set in RCODE with these values: 


[o No emors found | 


End-Ọf-File 
condition 


Duplicate key in 
file 


[16 | Key not found 


Figure 23. File-Handling Return Codes 
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Chapter 5. Query Functions 


This chapter contains a description of all query functions. 


If an SQL error occurs, an SQL return code is issued; you can 
investigate the error through the QRC and QHELP functions. 


For general information on creating SQL tables and queries, refer to 
the Application Prototype Environment: Guide. 
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QCREATE 


QCREATE — Create a Query 


Purpose To translate SQL statements to Application Prototype Environment representation. 
Syntax N QCREATE § 

N isthe name to be assigned to an SQL query. 

sS is an SQL statement. 


Example 'MYQUERY' QCREATE 'SELECT NAME,AGE FROM TABLEO1' 
QHELP '' 
Query <MYQUERY> created 


Usage Notes 
The SQL statement S is created and translated to Application 
Prototype Environment representation. The query Ñ can then be saved 
in an object library; it can also be executed directly with the QRUN 
function and modified with the QEDIT function. The query N can also 
be modified through Query Design (QDESIGN). You can optionally 
imbed existing queries or variables in your query statement, as 
shown in the following example: 


SELECT * FROM TABO1 WHERE COL3=V::VAR1 
INSERT INTO TAB2 Q:SELO01 


With one colon, the variable or query will be inserted into your current 
query definition immediately; with two colons, the insertion will occur 
when your query is executed. 
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QDESIGN and QEDIT 


QDESIGN — Call Query Design (QDESIGN) Menu 


Purpose To call the Query Design menu. 


Syntax QDESIGN 


Usage Notes 
Displays a menu containing options for designing SQL tables and SQL 
queries. 


QEDIT — Modify a Query 


Purpose To modify a query on a Query Design (QDESIGN) menu. 
Syntax CT] QEDIT N 
N is the name of a query. 
T is optional; it is one of the following query types: 
S SELECT Form 
f INSERT Form 
U UPDATE Form 
D DELETE Form 
F FREE Form 


Example QEDIT 'MYQUERY' 


Usage Notes 
The specified query is displayed on a QDESIGN panet where it can 
be modified and/or executed. The optional parameter T specifies the 
QDESIGN menu where the query will be displayed; this could be 
useful in designing one type of query (for example, an INSERT query) 
based on another type of query (for example, a SELECT query). 
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QEXEC 


QEXEC — Modify a Table or View 


Purpose To modify an SQL table or view. 
Syntax Z + V QEXEC D 
D js data input; or, a table or view name. 
V isa numeric vector of the form O N C, where: 
O is one of the following operation codes: 
0 Opens a table and reads the first set of data. 


1 Sorts column data. The order in which the columns are sorted is specified 
in the right argument D. 


2 Commits SQL updates; the @EXEC function remains in effect. 
3 Commits SQL updates and ends the QEXEC function. 

4 Undefined. 

5 Undefined. 

6 


Edits table data; the right argument D must be a nested array containing 

the table data to be edited. The first column of the array contains the 

editing commands (D, I, or U) for each row to be edited. A null symbol is 

defined in the first header row of the array. 

rd Scrolis backward. 

8 Scrolls forward. 

9 Scrolls to top. 

10 Scroils to bottom. 

1/ Purges current SQL cursor (erases pointers to table data). 

}2 Cancels (rollback). 

13 Reads current page again. 

14 Assign last result without header line to D (an APL variable that is 
specified as the right argument). 

15 Same as 14, except that the header line is also included. 


N Number of rows. The default is 20 rows. 


C Column sorting priority. The default is 1 (first column). Otherwise, columns are 
sorted left to right. This option is only valid when 0=0. 


Z isthe data result; it is empty if there is no result. 
Example 0 5 2 QEXEC 'MYTABLE' 


Result Opens a table called MYTABLE, sorts the data by the second column, and reads the first 
five rows of data. 


Usage Notes 
The operation codes are applied to the corresponding data elements 
in D. For example, OPEN operates on tables; INSERT operates on 
data to be inserted. 
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QEXEC 


Only one table may be open at a time; an open table must be closed 
before another table can be opened. 


Note: You should avoid any overlap between the SQL Rollback and 
Commit commands and the corresponding operations in QEXEC. 


Examples 
To open a table called MYTABLE, sort the data by the second 
column, and read the first five rows of data, you would specify the 
following: 
0 5 2 QEXEC 'MYTABLE' 
Then, to read the next page of data, you type: 


8 5 QEXEC '! 


If you want to store the result in an APL variable called DATA, you 
specify: 


15 QEXEC 'DATA' 
To add a command (or editing) column to DATA, you type: 
DATA + '.', DATA 
To delete a row, you specify: 
DATAL3;1] + 'D' 
To update rows, you type: 
DATA[S 5;1] e "UY? 
To replace some data, you specify: 


DATA[4;2] + c'NEWNAME' 
DATA[5;3] + c'NEWADDRESS' 
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QHELP 


To verify the data base updates and to read the new data again, you 
type: 


6 5 QEXEC DATA 
Finally, to save the data base work, you specify: 


2 5 QEXEC '' 


QHELP — Explain Query Return Codes 


Purpose To display a message relating to a specific query return code or to the previous query 
operation. 


Syntax Z+ QHELP P 
P isa retum code or an empty vector. 


Example QHELP '' 


Usage Notes 


If P is an empty vector, a message relating to the most recent query 
error will be displayed. Otherwise, a message relating to the specific 
return code will be displayed, as shown in the following example: 


QHELP 623 
Variable <> not included due to invalid shape <> 
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QINSERT 


QINSERT — Insert Table Data 


Purpose To insert data into a table. 
Syntax CP] QINSERT T 
P is the name of a table. 


P (optional) is a list containing the names of one or more panels to be used for inserting 
data. 


Example 'MYPAN' QINSERT 'MYTABLE' 


Result Displays the panel MY PAN, which can be used to enter data into the table MY TABLE. 


Usage Notes 
The Query Design (QDESIGN) panel for inserting data is displayed. 
You can then insert new rows of data into the table. 
You only specify panel P if you do not want to use the standard panel 
for inserting table data that is provided with QDESIGN. If you specify 
your own panel, you must specify at least the following fields: 
1. A Column names field with a label name of Q_COil@_I]. 
2. A Data type field with a label name of Q_CO2[Q_I;]. 
3. A Length field with a label name of Q_CO3([Q@_I;]. 
4. A NULLS field with a label name of @ CO4CQ_I;]. 


5. An Input field with a label name of Q_DIN[Q_7;9 J]. 
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QLIST — Display List of Queries 


Purpose To display a list of user-created queries. 


Syntax QLIST 


Usage Notes 


You can use commands and PF keys to perform operations on the 
queries in the list. Press PF 1 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 


Note: When QLIST is calted from the session manager, a panel will 
be displayed after you perform some work on a table or query; from 
this panel you may then perform a COMMIT/ROLLBACK operation on 
your work, if necessary. The same applies if QZIST is called from a 
menu. However, if you use QLIST from within one of your own 
functions, this panel is not automaticaily displayed. Thus, if you want 
to be prompted for a COMMIT/ROLLBACK operation when you are 
using QLIST within a function, you must code it yourself. 
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QMOD 


QMOD — Modify Table Data 


Purpose To modify data in a table. 


Syntax EP] QMOD T 


F 
P 
Example 'MYPAN' 


is the name of a table or view. 


(optional) is the name of a panel. 


QMOD ‘MYTABLE' 


Result Displays the table data from MYTABLE on the panel MY PAN; the table data can then be 


modified. 


Usage Notes 


The Query Design (QDESIGN) panel for modifying data is displayed. 
You can then update, delete, and insert rows of table data. 


You only specify panel P if you do not want to use the standard panel 
for modifying table data that is provided with QDESIGN. If you 
specify your own panel, you must specify at least three fields: 

1. A Heading field with a label name of Q@_HEA[L@_ 7). 

2. A Data field with a label name of Q_DAT[;Q_d]. 


3. A Command field whose label is @_ FCO. 


Note: The heading and data fields must be the same width. 
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QRC 


QRC — Display Query Return Code 


Purpose 


Syntax 


Example 


To display the return code from the last query operation. 
Ze QRC 
Z isa numeric scalar containing a retum code. 


QINSERT 'YOURTABLE! 
QRC 
690 
QHELP '' 
SQL error <-204>: <An unknown name was specified in the 


SQL statement> 


Usage Notes 


The return code from the last query operation is displayed. You can 
use the Q@HELP function to display the message associated with the 
return code, 


The return codes are divided into the categories shown in Figure 24. 


Description 
Successful operation. 


618 Result of function points to 
location of error, 


APL variable or object invalid or 


620-629 


missing. 
630-639 Query name conflict. 
640-649 Enter (VALENCE) errors. 
650-659 Erroneous use of query functions, 


such as giving an invalid number 
of parameters. 

660-669 Fullscreen error 

670-679 SYNTAX, RANK, and DOMAIN 


errors, normally due to invalid 
data. 

680-689 SQL input data is invalid or not 
recognized. 

690 SQL error; execution interrupted. 


SQL return code is displayed. 


Figure 24 (Part I of 2). Query Return Codes 
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QRUN 


Code 
691 


Description | 
SQL warning. SQL return code is 
displayed. 


692-698 Environment problems (CMS, 


TSO, auxiliary processors) 


Figure 24 (Part 2 of 2). Query Return Codes 


QRUN — Execute a Query 


Purpose To execute a query immediately. 
Syntax Z+ [C] QRUN Q 
@ isthe name of a query. 


C (optional) is an asterisk, which causes the column names to be displayed with the 
query result. 


Zz is a matrix containing the result. 
Example '+' QRUN ‘MYQUERY'* 


Result The query MY QUERY is executed and the result is displayed (with column headings) as a 
matrix in the session manager. 


Usage Notes 


The query @ is executed immediately and the result can be displayed 
in the session manager as a matrix. The matrix Z will be empty if the 
query does not have a data result. 


Specifying an asterisk as a left argument results in the column 
headings being included with the query result. 
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QUERIES and SQLFNS and TABLES 


QUERIES — Begin Designing Queries 


Purpose To call a menu containing options for designing SQL queries. 


Syntax QUERIES 


Usage Notes 
You design queries on panels reached from the QUERIES menu. 


SQLFNS — Show Query-Handling Functions 


Purpose To show a list of the available relational data base functions. 


Syntax SQLFENS 


Usage Notes 
The list includes a short description of each of the data base 
functions. For more information, use the SHOW command or the PF 10 
key against any of the functions in the list. 


TABLES — Begin Designing SQL Tables 


Purpose To call a menu containing options for designing SQL tables. 


Syntax TABLES 


Usage Notes 
You define SQL tables on panels reached from the TABLES menu. 
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TLIST and QPRICL 


TLIST — Show List of SQL Tables 


Purpose To show a list of all SQL tables. 


Syntax TLIST 


Usage Notes 
You can use commands and PF keys to perform operations on the 
SQL tables in the list. Press PF 1 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 


The information that is displayed in the list will be different depending 
on whether the authorization was set to “Administrator” or “User” in 
the QDESIGN profile. 


Purpose To change the default TSO data set JCL parameters for TSO files created as a result of 
SELECT queries. 


Syntax @PRJCL + new parameters 
Default: SPACE(1 1) CYLINDERS UNIT(SYSDA) 
Example QPRJÇL + 'SPACE(1 10) TRACKS UNIT(SYSDA) 


Result The new file is created with a first extension of one track; each of the extensions following 
the first one has 10 tracks. 


Usage Notes 
A new fite is created for each SELECT query result. If a file exists, 
you will be asked to select a new name, or to overwrite the old file. 
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Chapter 6. Object Library Functions 


Library Names 


This chapter describes the object library functions. A general 
description of the object library system is given in the Application 
Prototype Environment: Guide. 


In describing the object library functions the letter F is used to 
denote a library name, as shown in the following example: 


R + OINDEX F 


F might contain only a library name, but it might also contain various 
qualifiers. if F contains qualifiers, the values for both the library type 
and the CMS minidisk or the TSO catalog will be used to automaticaily 
update the OF TFM control variabie (or possibly the QLEVEL variable 
in TSO). 


Object Library Return Codes 


All object library operations set the following two variables: 
QRC This variable reports the outcome of the library file access. 


QRC? This variable reports the outcome of the operation for 
individual objects. If no objects are involved, as with the 
OCHECK function, QRC2 is set to empty. 


If the library access is successful, the variable QRÇ is set to 0. 
If it fails, ORG is set to a particular code depending upon the 
error and the library function involved. However, QRC =0 does 
not indicate that all objects have been successfully processed. 
Even if ORC is 0, your application code must also check ORC2, 
which is a vector of individual return codes for each object. 
These codes show, for example, whether or not the object was 
found in an object library. 
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Object Library Types 


Because object names are sorted to achieve the fastest 
possible access, QF€2 does not normally correspond to the 
name list given to a library function such as OGET. You can 
use the OHELP function to obtain a detailed report about each 
object processed. 


If you want to automatically receive a brief message for each 
object library function that does not produce an explicit result, 
you can use the A_SET function as follows: 


'LIBMSG' A_SET ‘ON' 
With this setting, for example, the OPUT function will report 


the number of successfully saved objects (as well as the 
number of those not saved successfully, if such is the case). 


An object library may contain both APL objects and objects created by 
any of the Application Prototype Environment design components. 
When stored, ail object names in an object library are preceded by 
two characters: a single letter and a colon. The letter identifies the 
object “type.” For instance, a P is used to identify an object as a 
panel. The following is a list of the valid object types for an object 
library: 


A: 


identifies a menu application. The object is a variable containing 
common information for a menu system created with Menu 
Design (MDESIGN). 


identifies a chart created with Chart Design (CDESIGN). The 
object is a variable containing all the information needed to 
redesign the graphical function. The graphical function 
generated by CDESIGN is not stored in an object library; 
instead, the variable representing this function is stored in the 
library. This graphical function is reestablished when the chart is 
read into the workspace again. Since CDESIGN and the two 
object library functions OLOAD and OGET can place a graphical 
function in the workspace, you should avoid giving another APL 
object the same name as the graphical function. By following this 
precaution you will avoid overwriting the APL object with the 
graphical function. 


identifies a file declaration created with File Design (FDESI GN). 

This object is a variable containing ali the information entered in 

FDESIGN, including the generated access functions. The access 
functions are established when the specified file is opened, not 
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when they are retrieved from the library. The access functions 
are then expunged from the workspace when the file is closed. 


identifies an APL latent expression. This object is a simple 
character vector that you define and should contain an 
executable APL expression. The APL expression will be 
executed when it is retrieved from an object library. If the latent 
expression is loaded together with a set of APL functions, it is 
called an object library application. If more than one latent 
expression is retrieved during the same library access, none of 
the expressions is executed. To retrieve a latent expression 
without executing it, you must use surrogate names. For more 
information about object library applications and surrogate 
names, see the Application Prototype Environment: Guide. 


identifies an APL function. A function that is retrieved from an 
object library will overlay any APL object (function, operator, or 
variable) of the same name, unless the function is retrieved with 
the OPGET function. 


is a library group. You may retrieve a set of objects that are 
grouped together by creating a library object group. You may 
then retrieve the entire group of objects by specifying only the 
group name. For more information about using groups, see the 
Application Prototype Environment: Guide. 


identifies an image created with Image Design (IDESIGN). This 
object is a variable containing the image pattern and the 
necessary information to redesign the image. It also contains 
the specific image display function. An image is handled in the 
same way as a chart (see C:) above. 


identifies a list created with List Design (LDESIGN). This object 
is a variable containing the information that is used both when 
the list is displayed and when it is redesigned. 


identifies a menu created with Menu Design (MDESIGN). This 
object is a variable containing the information that is used both 
when the menu is displayed and when it is redesigned. The 
menus and the menu application (see A: above) are closely 
linked to each other. Thus, it is recommended that you keep 
these objects in the same object library and that you retrieve 
both types of objects whenever using or updating them. 


identifies an APL operator. An operator is treated in the same 
way as a function (see F: above). 
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identifies a panel created with Panel Design (PDESIGN). This 
object is a variable containing the information that is used both 
when the panel is displayed and when it is redesigned. If input 
validation was specified in PDESIGN, an input function is stored 
as a part of the panel variable. This input function is established 
as a local function only when it is needed and is then expunged 
from the workspace. 


identifies an SQL query created with Query Design (QDESIGN). 
This object is a variable that contains the formal definition of an 
SQL query. Since the internal format of a query is 
language-independent, the query definition will be displayed in 
the current national tanguage, even if it was defined when 
another national language was current. 


identifies an APL variable. This is used to store your own APL 
variables. This does not include the variables that contain the 
formal definitions of objects such as panels, declarations, and so 
on. These objects are stored with the type codes described 
above. 


Specifying an object type and a colon for APL objects when they are 
stored in an object library is optional; the correct object type wiil be 
assigned automatically. However, any object created by one of the 
Application Prototype Environment design components must be 
preceded by the correct object type and a colon when stored; 
otherwise, the system will assume that the object is an APL object. 


Except for the APL restriction that APL object names may not 
duplicate each other, duplication of names is otherwise allowed. 
Thus, a menu and a panel could have the same name within a single 
object library because their respective prefixes (M: and P:) would 
distinguish them. However, two APL functions with the same name 
would not be allowed within the same object library. 


Object Library Naming Conventions 
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Whenever an object library function requires a library name as a 
parameter, the following rules apply: 


iF 


You may use a single name as the library name. In this case, the 
remainder of the name is taken from the OF TEM global variable 


QLEVEL is not empty). if QLEVEL is empty, your userid will be 


used as the catalog name. 


2. If you specify more than two names, you can use either blanks or 
dots to separate the names. This convention is independent of the 
operating environment. 


Furthermore, the second name will update QF2FM. For example, 
with the following statement in TSO: 


OINDEX ‘DATA MYLIB' 


OFTFM would be updated to contain MYZLIB. Then, if your next 
operation is, for example: 


'PUNCS' OGET 'MYFUNC! 


you will attempt to retrieve the function MY FUNC from the library 
called USERID. FUNCS .MYLIB. 


3. If three names are specified, the following wiil occur: 


CMS the third name is interpreted as the letter of the minidisk 
and will be used to update OFZ FM. 


Tso the first part is interpreted as a catalog name and will be 
used to update OLEVEL. 


4. If more than three names are specified, the following will occur: 
CMS treated as invalid. 
Tso all names except for the last two names will be 


interpreted as the catalog name and will be used to 
update QLEVEL. 
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LIBFNS and LIBRARIES 


LIBFNS — Display List of Object Library Functions 


Purpose To display a list of the available object library functions. 
Syntax LIBENS 


Usage Notes 
The list includes a short description of each object library function. 
For more information, use the SHOW command or the PF 10 key 
against any of the functions in the list. 


LIBRARIES — Display Selected Libraries 


Purpose To display selected object libraries in a list from which operations may be performed on 
individual libraries. 


Syntax LIBRARIES S 
S is an expression for sclecting a set of object libraries. 
Example LIBRARIES 'AB*+ APELIB2 *' 


Result Finds and displays any libraries that begin with the letters AB and that reside on any disk in 
the CMS environment. 


Usage Notes 
The function selects object libraries from the host system according to 
the selection expression. You may insert asterisks in the selection 
expression to represent zero or more letters. From the list you can 
press PF 1 to see the available operations. 


130 


LISTLIB 


LISTLIB — Display Library Contents 


Purpose To display the contents of an object library in a list from which operations may be 
performed on individual objects. 


Syntax LISTLIB L 
L isthe name of an object library. 
Example LISTLIB ‘ABC APELIB2 A' 


Result Displays a list of the individual objects contained in the library ABC APELIB2 A. 
Commands may then be issued against the individual objects. 


Usage Notes 
The LISTLIB function uses the OINDEX function to display the 
contents of an object library. You may then perform operations on any 
of the objects in the library. For example, you can retrieve an object 
with the OGET command if it is not in the workspace. You can then 
edit the object and store it back in the object library with the OPUT 
command. 


To see a list of the available commands, press PF 1 from the list of 
library objects. 
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OCHECK 


OCHECK — Check Library Characteristics 


Purpose 


Syntax 


Example 


Result 


To check the characteristics and utilization of an object library. 


T*OCHECK F 


F isthe name of the library to be checked. 


T isa character matrix containing a description of the library. 


OCHECK ‘LIBO1' 


Return Codes 


86-01-16 19.27 
Version 
Objects 
Objects 
Records 
Records in use. 8 
Record length. 16384 
Blocks/record. 31 
Pad bytes/record. 16 
Block length.. 528 
Total blocks 620 
Blocks used... 195 
including indices... 10 
BIOCKS FLCC. creer eveee 425 
QRC Explanation 
0 Operation successful 


830 Cannot read record 

835 Library not found 
(Host) Cannot open library 
(Host) Cannot read record 


Figure 25. Return Codes for OCHECK 


Note: “ Host” in the above chart means that the code can be issued 


by either CMS or TSO. 
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OCLOSE 


OCLOSE — Close a Library 


Purpose To remove an object library from the rapid access chain (cancelling the OOPEN command). 
Syntax OCLOSE F 


F is the name of an object library, or an integer file number assigned to the library with 
the OOPEN command. 


Example QOCLOSE 'LIB01' 


Result The library LIBO1 is removed from the rapid access chain. 


Usage Notes 
The library is removed from the list of “open” libraries, and is no 
longer included in sequential searches. However, the file number 
assigned by 0OPEN remains associated with the library. It can still 
be referred to by that number, and the number cannot be reused for 
some other library. (To free the file numbers, issue the OZWD 
command.) 


Return Codes 


ORC Explanation 
0 


Operation successful 
-832 Library already closed 
835 Library not found or not previously opened 


Figure 26. Return Codes for OCLOSE 
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ODESIGN and OCREATE 


ODESIGN — Call Object Library Design (ODESIGN) Menu 


Purpose To call the Object Library Design menu. 
Syntax ODESIGN 


Usage Notes 
Displays a menu containing options for performing operations on both 
object libraries as well as on individual objects in an object library. 


OCREATE — Create a Library 


Purpose To initiate an object library (without putting anything into it). 
Syntax OCREATE F 


| 
F isthe name of the library to be created. 
Example OCREATE 'LIB01' 


Result The library LI B01 is created. 


Usage Notes 
The tibrary is created, using characteristics supplied in the global 
variables OFTFM, QNPARMS, and (under TSO only) QLEVEL. 
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ODESIGN and OCREATE 


Return Codes 


QRC Explanation 
0 Operation successful 


gl Too many objects or too few records 
812 Library name in use 

813 Too many records 

814 Record length out of range 

815 Record length must be multiple of 8 
816 Too many objects 

817 Too many blocks 


818 Too many blocks for this record length 
820 Bad library name 
(Host) Cannot create library 
(Host) Cannot write record 


Figure 27. Return Codes for OCREATE 


CMS the variable OF TFM provides the remaining parts of the 
library identifier. The default value is APELIB2 A. Thus, 
for example, the command OCREATE 'LIBO1' creates a 
file named L7B01 APELIB2 and saves it on the user's 
A-disk. 


Tso the variable QLEVEL provides the data set level. It is 
normally an empty vector, which causes the top level 
qualifier to default to the user’s userid. The variable 
QETEM provides a third level qualifier, normally 4PELIB2. 
Thus, if user EDWIN issues the command OCREATE 
'LIB01', the data set created is named 
EDWIN .LIBO1.APELIB2. 


The variable QNPARMS controls several object library functions. Only 
the first four elements are associated with OCREATE: 


QNPARMS[1] Sets the number of records allocated to a library. 
QNPARMS[ 2 ] Sets the physical record length. 

QNPARMS[ 3] Sets the number of objects that can be stored. 
QNPARMS[4 J Sets the number of blocks per physicat record. 


For more details, see ONPARMS on page 151. 
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ODROP 


ODROP — Delete a Library 


Purpose 


Syntax 


Example 


Result 


Usage Notes 


To discard object libraries. 
ODROP F 

F isa library name. 
ODROP 'LIB01' 


Library LIBO1 is erased. 


The named library is erased. 


Return Codes 


ORC 
0 


824 
-838 


Figure 28. 


Explanation 


Operation successful 
Must have library NAMES 
Library not dropped 


Return Codes for ODROP 
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OEND 


OEND — Expunge Library Control 


Purpose To clean up the workspace after using the object library functions. 


Syntax OEND 


Usage Notes 
All indices and some other global variables created by the object 
library functions are expunged from the workspace. All file numbers 
assigned to libraries by OOPEN are freed. Object lists used by 
OSCRUB are nullified. (However, none of the objects in the list are 
expunged.) 


Return Codes 
None — the variable ORC is set to empty. 
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OERASE 


OERASE — Erase Library Objects 


Purpose To erase objects from an object library. 


Syntax F OERASE 0 


F 


o 


Example ‘'ZZBO1' 


is an object library name or an integer file number assigned using OOPEN. 


is a list of objects. 


OERASE 'L:DATES Q:PAYMENTS' 


Result The list and the query are both erased from LIBO1. 


Usage Notes 


Return Codes 


The listed objects are removed from the library. 


All objects to be erased must be named explicitly in the object list. If 
one of the objects is a group or an application, the group name list is 
erased, but the individual items in the group are not affected. To 
erase a group and all the items in it, follow this example: 


'LIB02' OGET 'TEMP+GRP2' 
‘LIBO2' OERASE 'GRP2' A_MAD TEMP 


QRC? 


Explanation 


ORC Explanation 


0 Operation successful 0 Object erased 
-825 No object names given 859 Object not processed 
830 Cannot read record -865 Object not found 


835 Library not found 866 Duplicate objects found 
(Host) Cannot open library 


(Host) Cannot write record 


Figure 29. Return Codes for OERASE 
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OGET 


OGET — Retrieve Selected Library Objects 


Purpose To retrieve objects from an object library and place them in the active workspace. 


Syntax F OGET 0 


F 


0 


Example 'LŁIBO1' 


is an object library name, or an integer file number assigned using QOPEN. 
is a list of objects. 
Optionally, the first item in the object list can be an integer number. This is a “call 


number”. It identifies the objects as objects which will eventually be expunged by the 
OSCRUB function. 


OGET '6 DATES PAYMENTS" 


Result The objects DATES and PAYMENTS are retrieved from the library LIBO1 and are 
assigned the call number 6. 


Usage Notes 


A special case occurs when a file number of 0 is given. Then, all 
libraries previously placed in the rapid access chain by the OOPEN 
command may be searched for the objects. The search sequence is 
determined by the priorities specified with OOPEN. The program 
attempts to find all the objects in the first library; any not found are 
searched for in the second; and so on, The search ends when all 
objects have been found, or when the end of the list of open libraries 
is reached. 


Usually, the length of QRC2 equals the number of names in object 
list O. However, if any object is a group, the length of QRC2 is larger 
than the number of names, and there is no simple relationship 
between QRC2 and O. The same is true if objects are being 
recovered from two or more concurrently opened libraries. 


ORC Explanation QRC? Explanation ] 
0 Operation successful 0 Object successfully ret rieved 
822 No libraries open 859 Object not processed 
-825 No object names given 865 Object not found in library 
830 Cannot read record 866 Duplicate objects found in library 
835 Library not found 867 Function/variable name c onflict 
867 One or more function 868 Expression execution failed 


or variable names conflict 
(Host) Cannot open library 
(Host) Cannot read record 


Figure 30. Return Codes for OGET 
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OHELP 


OHELP — Display Information Message 


Purpose To display an information message on the outcome of the last object library operation. 
Syntax Z + OHELP 
Example 'LIBO1' OGET 'F:MYFUNC P:MYPANEL I:MYIMAGE' 
OHELP 
2 objects loaded: 
F:MYPUNC P:MYPANEL 
1 object not found in file: 
I:MYIMAGE 
Result A message is displayed that describes the last object library operation. 
Usage Notes 


OHELP always reports the outcome of the last object library 
operation, regardless of which function was last executed. Where 
appropriate, the outcome for individual objects is also reported. 


During application devetopment you might want to set the LTBMSG 
keyword of the A_SET function as follows: 


'LIBMSG' AO _SET 'ON' 


This setting will cause brief messages associated with library 
operations to be displayed. For example: 


5 objects loaded 
2 objects not found 


You could then use the QHELP function to find the names of the 
objects not found. 


In an application where the brief messages are not displayed, the 
message produced by QHELP might be helpful to the user. For 
instance, you could use the following approach: 


L.. 

C12] +(0SQRC)/CONTINUE a If ORC ok, print message from OHELP 
(13) 'A' SMSC OHELP a Otherwise, go to CONTINUE 

{..J 
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OINDEX 


OINDEX — Display List of Library Objects 


Purpose To get a list of the objects in an object library. 
Syntax R + OINDEX F 


F is the name of an object library, or an integer file number assigned using the OOPEN 
function. 


Example OINDEX 'LIBO1' 


Result Displays list of objects contained in LI B01. 


Usage Notes 
The explicit result, R, is a character matrix formatted as follows: 


1. The first column is a letter representing the object type: 


A = menu application L = list 

C = chart M = menu 

D = file declaration O = APL operator 
E = API, latent expression P = panel 

F = APL function Q = query 

G = library group V = APL variable 
I = image 


2. The second column is a colon. 


3. The remaining columns contain the object names. 


Return Codes 


ORC Explanation 


0 Operation successful 
835 Library not found 
-850 Library is empty 
-851 No objects found 
(Host) Cannot open library 
(Host) Cannot read record 


Figure 31. Return Codes for OINDEX 
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OLIST 


OLIST — Display List of Libraries 


Purpose 
Syntax 


Example 
Result 
Example 


Result 


To display a list of object libraries. 
R*OLIST S 
S isa character vector containing a search specification. 
Under CMS, its format is identical to that used by the CMS LISTFILE command. 


Under TSO, it may contain one or more levels that are delimited by periods; the last 
two of these may be replaced by asterisks. 


OLIST '*IBt a CMS environment 
Displays a list of all libraries ending with the characters 7B. 
OLIST ‘APL.*.APELIB2' a TSO environment 


Displays a list of all libraries where APELIB2 is one of the levels. 


Usage Notes 


The explicit result, R, is a character matrix containing a list of 
libraries. Under CMS, it includes file characteristics and creation 
dates. 


If S is an empty vector or if only one name is given, the rest of the 
search specification is obtained from the global variable QET EFM. 


Return Codes 


ORC Explanation 
0 


Operation successful 
828 Bad syntax in data set specification (TSO only) 
829 Failed to build library list (TSO only) 
831 Data set allocation fatled (TSO only) 
-834 No object libraries found 
(Host) Cannot operate without A-disk (CMS only) 
(Host) Could not open file 


Figure 32. Return Codes for OLIST 
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OLOAD 


OLOAD — Retrieve All Library Objects 


Purpose To copy all objects from an object library into the active workspace. 
Syntax F OLOAD C 
C is the call number; it can be an integer, or an empty vector. The call number, if given, 
must be unique to this library. It identifies all the objects loaded from the library to 
be eventually expunged by the OSCRUB function. 
F is an object library name, or a file number assigned using the OOPEW function. 
Example '£IB01' OLOAD '' 
Result All objects are retrieved from the library LIJBO1 and are placed in the active workspace. 
Usage Notes 


All objects in the library are copied into the active workspace. 


Note: OLOAD retrieves objects faster than OGET. Therefore, if you 
want some objects to be loaded as quickly as possible, it is best to 
put them in a separate object library and retrieve them with an 
OLOAD command. 


Return Codes 


If the file access is successful, and if all objects are retrieved, the 
variable QRC is set to 0. If it fails, ORC is set as in the table below. 
The variable QRC? contains a vector of individual return codes for 
each object. 


ORC Explanation 
0 


| ORC2 Explanation 
Operation successful 0 


Object successfully retrieved 


830 Cannot read record 867 Function/variable name conflict 
835 Library not found 868 Expression execution failed 
867 One or more function -870 Item (group or application) 


or variable names conflict not loaded 
871 Failed to load object(s) 
872 Library already loaded 
or call number in use 
(Host) Cannot open library 
(Host) Cannot read record 


Figure 33. Return Codes for OLOAD 
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OOPEN — Open a Library 


Purpose To prepare an object library for rapid access and (optionally) specify a search order for 
concurrently opened libraries. 


Syntax CV] OOPEN F 


F isthe name of an existing object library. 


V isan optional parameter. If specified, it consists of one or two positive integers. The 
first integer is an arbitrary file number; the second specifies a priority number which 
determines the order in which concurrently open libraries will be searched by the 
functions OGET and OPGET. (Low-numbered priorities are searched first.) 


Example 9 QOPEN 'LIBO1' 


Result The library LJ B01 is opened with the arbitrary file number 9. 


Usage Notes 


Return Codes 


The library is prepared for access, with the file number and search 
priority given in the left argument. If V is omitted or empty, a default 
file number is assigned. If no priority number is given, it defaults to 0 
— the highest priority. 


If two or more libraries are opened with the same priority, they are 
searched in reverse chronological order — that is, the most recently 
modified library is searched first. 


ORC Explanation 
0 Operation successful 


823 You must give library name 
826 Duplicate file number 

830 Could not read record 

835 Library not found 

(Host) Could not open library 
(Host) Could not read record 


Figure 34. Return Codes for OOPEN 


To remove a library from the rapid access chain, issue the OCLOSE 
command; for example: 


OCLOSE 'L1801' 


To close all open libraries and free ail the file numbers, issue the 
OEND command. 
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OPGET 


Under TSO, it is necessary to indicate whether you wish to write in a 
library explicitly opened by OOPEN. To allow writing, set 
ONPARMS[ 8]~+1 before issuing the OOPEWN command. Otherwise, 
leave it set to 0 (default state). 


OPGET — Retrieve Unique Library Objects 


Purpose To retrieve objects out of an object library, provided they are not in the active workspace. 
Syntax F OPGET 0 

F isan object library name, or an integer file number assigned using QO PEN. 

O isa list of objects. Optionally, the first item in 0 can be an integer “call number”. 


Example ‘LIB01' OPGET '6 DATES PAYMENTS! 


Result The objects DATES and PAYMENTS are retrieved from the library LZ B01 and are 
assigned the call number 6, unless they are already in the workspace. 


Usage Notes 
The syntax and usage of this function are identical to those of OGET, 


except it protects existing objects from being overwritten. 


Return Codes 
If any of the objects are found to exist in the active workspace, the 


return cade in ORC2 is 864. 


ORC Explanation ORC2 Explanation 
0 Operation successful 0 Object successfully retrieved 

822 No libranes open 859 Object not processed 

-825 No object names given 864 Object not copied (already 

in workspace) 

830 Cannot read record 865 Object not found in file 

835 Library not found 866 Duplicate objects found in file 
{Host) Cannot open library 867 Function/vanable name conflict 
{Host) Cannot read record 868 Expression execution failed 


Figure 35. Return Codes for OPGET 
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OPUT 


OPUT — Store Library Objects 


Purpose 


Syntax 


Example 


Result 


To put (store) objects into an object library, or to replace objects already in it. 
F OPUT 0 

F isan object library name, or a file number assigned to it by OOPEN. 

O isa list of objects. 

‘LIBO1' OPUT 'Q:MYQUERY P:PANO1 I:IMAGEO1' 


If the library L7B01 does not exist, it is.created automatically. The objects given in O are 
stored in L[B01. 


Return Codes 


If QRC2[N] is 0, then object ¥ has been filed successfully. If 


QRC2[N 1) is positive, object N has not been filed. If QRC2[N] is 
negative, the object has been filed, replacing an earlier version. 


{ ORC Explanation Q@RC2 Explanation | 
0 Operation successful 0 Object successfully stored 

-809 Created new library -802 Object replaced 
-825 No object names given 855 Object not found in workspace 
830 Could not read record 857 Invalid object name 
841 Not enough space for object 858 Function is not locked 
842 Library is full 859 Object not processed 
843 Library index is full 860 Wrong data type for group, 
(Host) Could not open file application, or expression 
(Host) Could not read record 
(Host) Could not write record 


Figure 36. Return Codes for OPUT 
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OSCRUB 


OSCRUB — Remove Library Objects from Workspace 


c 


Syntax OSCRUB 


c 


Purpose To expunge library objects from the workspace, cither completely or selectively. The objects l 
to be expunged are identified by the call numbers given when they were loaded by the i 
functions OGET, OPGET, or OLOAD. ! 


may contain one or more integers (call numbers) indicating which objects are to be 


i 
| Example OSCRUB 6 27 
| 


Usage Notes 


The following applies to OSCRUB: 


1. 


If C contains one or more positive integers, then only the objects 
identified by these integers are expunged. However, an object 
may be associated with more than one call number. In such a 
case, the object will not be expunged unless all of its cali numbers 
are being expunged. 


lf C contains one or more negative integers, then all objects 
except those identified by these numbers are expunged. 


If C is an empty vector, then all objects associated with call 
numbers are expunged from the workspace. Each integer comes 
from a specific use of the functions OGET, OPGET, or OLOAD. 
Each time any of these is called, you may include a positive 
integer as the first item in the object list. 


Objects which do not have call numbers cannot be expunged by 
OSCRUB. 


For example: 


'MAINFILE' OGET '22 FN1 VAR1 GRP2' 


The number 22 identifies all the objects extracted from MAINFILE by 
this specific call to OGET, including the individual objects in any 
groups present (such as GRP2). Subsequently, a command such as: 


OSCRUB 22 


will expunge the objects. 
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OSETDFLT 


Alternatively, 
OSCRUB ~ 22 


will expunge all objects except those identified by 22. 


Return Codes 
If execution is successful, the variable QRC is set to 0. If it fails, ORC 
is set as follows: 


ORC Explanation 


0 Objects successfully expunged 
848 Argument must be integer(s) 


Figure 37. Return Codes for OSCRUB 


OSETDFLT — Set Defaults for Global Variables 


Purpose To set default values of global variables used by the object library functions. 


Syntax OSETDFLT 


Usage Notes 
Global variables such as OF TEM and ONPARMS are set to default 
values. 


Return Codes 
The variable ORC is always set to 0. 


148 


OFTFM — Define Library Name 


Purpose To set the default for part of an object library name. 


Usage Notes 


Pe 


‘libtype minidisk' a {CMS) 
‘libtype' a (TSO) 
"APELIB2 A’ a (CMS) 
"APELIB2' a (TSO) 


Under CMS, if you want your libraries to have a library type other than 
APELIB2, or if they are to reside on a disk other than your A-disk, 
you must set OF TFM accordingly. 

The defaults values are: 


CMS APELIB2 * 
TSO APELIB2 


Note that QFTFM is updated each time you use an object library 
function where you specify more than the library name as a 
parameter. Thus, if you issued the following command: 


'LIBO1 APELIB2 Bt OPUT 'D:FILEO1' 


QETEM will be set to 'APELIB2 B' inaCMS environment. 
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Purpose To set the user library catalog in TSO. 


Syntax OLEVEL + V 


v 


is a library catalog name; or, it is an empty vector, in which case QLEVEL is set to 
the user's own userid. 


Example QLEVEL + 'SOME.CAT' a use catalog SOME.CAT 


Usage Notes 


Determines which user library catalog will be used when creating and 
accessing object libraries. The default is normally set during 
installation. 


Note that QLEVEL is updated each time you use an object library 
function where you specify more than two levels of names as a 
parameter. Thus, if you issued the following command: 


OINDEX 'MASTER.CAT.LIBO1.APELIB2' 


OLEVEL will be set to MASTER.CAT and QFTFM will be set to 
APELIB2. 
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— Control Object Library Operations 


i Purpose To control object library functions, 


| Syntax QNPARMSLW) 


N 


Usage Notes 


is a numeric parameter in the range 1 - 8. 


oS 
rs 
b 
Jæ 


MS[1] 


QNPARMS[ 2] 


QNPARMS[4] 


Ls} 
iz 
fa 


i 


RMSCS] 


This is the number of records allocated to a library 
when it is created. 


Under CMS, the records are not created untess they 
are actually used, so a larger allocation does not 
waste file space. 


Under TSO, however, all the records are initiated 
when the data set is created. 


Physical record lengths. Depending on the contents 
and usage of the library, you may modify this 
between a minimum of 1024 and (under CMS) a 
maximum of 61440 bytes. Under TSO, the maximum 
is lower, and depends on the physical track length of 
the DASD being used. (For example, the 3350 has a 
maximum of 19064 bytes.) At the low end of the 
range, file efficiency will fatl off unless most objects 
are very small. At the high end, you may encounter 
limitations due to: (a) shared variable buffer size, or 
(b) workspace working area. 


Capacity of library index — that is, the number of 
objects which can be stored. You can adjust this if 
you expect to have a larger or smaller number of 
objects. A reasonable number of space entries has 
little impact on performance. 


Number of blocks per physica! record (the default is 
also the maximum: 31). This parameter should not 
be changed, except in a few cases where a library is 
being optimized for a particular object size. 


Controls the messages automatically returned by the 
object library functions. It has the following possible 
values: 
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IS 
& 
ro 
ES 


RMS(8] 


0 Suppress all direct tibrary messages. 
1 issues messages or any positive integer. 


Note: This parameter is set and queried by the 
LIBMSG keyword of the A_SET function. 


Reserved. 


Controls the removal of the system design 
components. If a component is not in the workspace 
when needed, that component (as well as other 
components that are needed) are automatically 
loaded. The values of ONPARMS7 are: 


0 Do not remove any components from the 
workspace. 


1 Remove all other design components from the 
workspace before an individual component is 
loaded. This is the default. 


2 Same as 1, but also remove the design 
component after it has been used. 


The design components are: 


CDESIGN 
FDESIGN 
IDESIGN 
LDESIGN 
MDESIGN 
PDESIGN 
QDESIGN 
DOCUMENT 


is used in TSO only and indicates whether an object 
library is to be updated when it has been explicitly 
opened by the QOPEN function. The values are: 

0 read only (default). 


1 update aliowed. 
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iss] 
Cy 


ORC — Check Library Return Code 


Usage Notes 


Purpose To check the return code for an object library operation. 


Syntax ORC 


In general, a return code of 0 indicates a successful library operation. 
A negative return code usually indicates that some deviation was 
detected but that the operation was still successful. A positive return 
code indicates that the operation failed. To ensure reliability, ORC 
must be checked after execution of any of the object library functions. 


To receive a brief message when an object library function returns an 
explicit result, set the LTBMSG keyword of the A_SET function as 
follows: 


"LIBMSG' A_SET 'ON' 


You can also use the OHELP function to display a report on the last 
library operation. 
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Summary of ORC Return Codes 


831 
833 
835 
835 
836 
841 
842 
843 
848 
867 


These return codes appear in ORC. A message is issued when any of 
these conditions occurs. (To suppress messages, set 'LIBMSG' 
A SET 'OFF'.) 


An asterisk (*) indicates that return codes can be issued by any of 
several functions. Return codes marked H are supplied by the host 
system. If no previous result is available, QRC is empty. 


Message or 
Explanation 


No objects found 

File is empty 

File <name> not dropped 

No files found 

File already closed 

No object names given 

Created new library 

*Successful operation 

Too many variables shared with AP100 
File processor AP210 not available 
Too many objects or too few records 
File name in use 

Too many records 

LRECL out of range 

LRECL must be multiple of 8 

Too many objects 

Too many blocks 

Too many blocks for this LRECL 

Bad file name 

*File not open 

No files open 

Must have file NAME 

Must have file NAMES 

Duplicate library number 

File processor AP210 not available 

Bad syntax in data set specification (TSO only) 
Failed to build library list (TSO only) 
*Could not read record 

‘Data set allocation failed (TSO only) 
Invalid syntax in data set specification 
*File not found 

File not found or not previously opened 
Specified file is not a Version 2 file 

Not enough space for object 

File is full 

File index full 

Argument must be integer(s) 

*One or more function or variable names conflict 


Figure 38 (Part 1 


of 2). Summary of Object Library Return Codes 
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Message or 
Explanation 


Failed to Joad object(s) 

File already loaded or call name in use 

Surrogate names (renaming) not allowed for menus and applications 
Multiple latent expressions 

Cannot access file in write mode 


Could not open file 

Could not open file 

Cannot operate without A-disk (CMS only) 
Could not create file 

Could not read record 

Could not write record 


Figure 38 (Part 2 of 2). Summary of Object Library Return Codes 


QRC2 — Check Return Code for Library Objects 


Purpose To check the return code for each object processed by an object library operation. 
Syntax QRC2 
Usage Notes 


In general, a return code of 0 indicates a successful library operation. 
A negative return code usually indicates that some deviation was 
detected but that the operation was still successful. A positive return 
code indicates that the operation failed. To ensure reliability, QRC 2 
must be checked after verifying that QRC is equal to 0. 

Note: Normally your name list and the contents of QRC2 will not 
have a one-to-one relationship. If your name list includes groups, the 
name list and QRÇ2 will not even be of the same length. To verify 
the result for specific library objects, use the OHELP function. 
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ORC2 


Summary of QRC2 Return Codes 


These return codes appear in QRC2 when any of the functions such 
as OLOAD, OGET, OPGET, OPUT, and OERASE are called. Do not 
check QRC2 without first checking that QRC=0. 


Message or 


ORC2 Explanation 
~870 Item (group or application) not loaded 
865 Object not found in file 
~ 802 Object replaced 
0 *Successful operation 
847 File access functions not reconstructed 
855 Object not found in workspace 
856 Object not of this name class 
857 Bad object name 
858 Function is locked 
859 Object not processed. 
860 Wrong data type for group, application or expression 
864 Object not copied (already in workspace) 
865 Object not found in file 
866 Duplicate objects found in file 
867 Function/variable name conflict 
868 Expression execution failed 


Figure 39. Summary of Return Codes for Library Objects. The asterisk (*) indicates that return codes can be 
issued by any of several functions. If no previous result is available for individual objects, then ORC 2 is 
empty. 


Chapter 7. Auxiliary Functions 


The auxiliary functions are intended to be used primarily during 
application development. Thus, they are normally issued from the 
session manager. 
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AUXILS and DCLCOPY 


AUXILS — Display List of Auxiliary Functions 


Purpose To show a list of available auxiliary functions. 
Syntax AUXILS 


Usage Notes 
The list includes a short description of each of the auxiliary functions. 
For more information, use the SHOW command or the PF 10 key 
against any of the functions in the list. 


DCLCOPY — Copy File Declarations 


Purpose To copy file declarations from an Application Prototype Environment Version 1 workspace 
to a Version 2 workspace and to convert the declarations to the new format. 


Syntax DCLCOPY 


Usage Notes 
You are prompted for information including the names of the 
declarations to be copied. All named declarations are copied and 
converted. 


This function is only to be used during conversion from Version 1 to 
Version 2 of the product. 


Note: For this function to work, the FDESIGN component must be 
loaded. 
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DCONVERT 


DCONVERT — Convert File Declarations 


Purpose Converts a file declaration from an Application Prototype Environment Version | 
workspace to the format used in Version 2. 


Syntax DCONVERT D 
D isthe name of a Version 1 declaration. 


_ Example DCONVERT ‘DECLO1' 


Usage Notes 
The file declaration is converted to the new variable format and the 
old variables are expunged. 


This function is only to be used during conversion from Version 1 to 
Version 2 of the product. 


Note: The FDESIGN component must be loaded because the 
OCONVERT function generates new access functions. 
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A_DSPLY 


4 _DSPLY — Display a Nested Array 


Purpose To illustrate the structure of nested and mixed arrays. 


Syntax A_DSPLY A 


A 


Usage Notes 


is any array. 


The A_DSPLY function is identical to the APL2 DISPLAY 
workspace. 


The A_DSPLY function illustrates the shape of an array by placing 
boxes around all simple arrays. Nested arrays will be shown as boxes 


within boxes to indicate the level of nesting. 


The A_DSPLY function uses the following characters to convey 
shape information: 


>ort Indicates a dimension of at least one. 


eor¢ Indicates an axis of length zero. If an array is empty, its 
prototype is displayed. 


Note: When none of the above characters appears, there is no 
dimension. 


The following characters are used to convey type information: 


ag Indicates numeric 
+ Indicates mixed 
€ Indicates nested 


Indicates a scalar character which is at the same depth as 
non-scalar arrays 


Note: When none of the above characters appears, it means that 
there is a character array that is not a simple scalar. 


For very large arrays it might be better to use the A_SHP function. 
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PANELCOPY and PCONVERT 


PANELCOPY — Copy Panels 


Purpose To copy panels from an Application Prototype Environment Version | workspace to a 
Version 2 workspace and converts the panels to the new format. i 


Syntax PANELCOPY 


Usage Notes 
You are prompted for all necessary information, including the names 
of the panels to be copied. All named panels are copied and 
converted. You are also prompted to specify whether you are copying 
from a VS APL or from an APL2 workspace. 


This function is only to be used during conversion from Version 1 to 
Version 2 of the product. 


PCONVERT — Convert Panels 


Purpose To convert the three variables of a panel definition from an Application Prototype 
Environment Version | workspace to the variable format used in Version 2. 


Syntax PCONVERT P 
P isthe name of a Version 1 panel. 


Example PCONVERT 'PAN01' 


Usage Notes 
The panel definition is converted to the new variable format and the 
old variables are expunged. 


This function is only to be used during conversion from Version 1 to 
Version 2 of the product. 
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A_COPY and A_FNS 


A_COPY — Copy APL Objects 


Purpose To copy Application Prototype Environment objects between workspaces. 
Syntax W A_COPY L 

W isthe workspace (WSID) to copy from. 

L isa list of object names prefixed by their object types. 
Example '1005 MYAPE' A_COPY 'P:PANX M:MENY' 


Result Panel PANX and menu MENY are copied from the workspace MYAPE in library 1005 into 
the current workspace. 


Usage Notes 
The named objects are copied to the active workspace. In the above 
example, the elements of the expression are: 


1005 library number (optional) 
MYAPE workspace name 
P:PANX the name of a panel 
M:MENY the name of a menu 


A_FNS — Display APL Function Names 


Purpose To display the names of all APL functions in the workspace. 
Syntax Z + A_FNS 


Z isa matrix containing the names of all APL functions in the workspace. 


Usage Notes 
Z displays the names of all user functions across the screen. 
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A_HELP and A_NMS 


A_HELP — Display Error Information 


Purpose To display additional error information. 
Syntax A_HELP 
Example SMOD 'Z2Z' 
Panel(s) <ZZZ> not found 
&_HELP 
The function SMOD has found an error 


To see the function usage, try: 
A_SHOW 'SMOD' 


Usage Notes 
Information is taken from OET and DEM and then displayed. 


A_NMS — Display all Objects 


Purpose To display all objects in the workspace. 
Syntax Ze A_NMS 


Z isa matrix that contains all objects in the workspace. 


Usage Notes 


Z displays the names of all objects in the workspace across the 
screen. Each name is preceded by a prefix indicating its object type. 
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A_OPS and A_SHOW 


A_OPS — Display the Names of Operators 


Purpose To display the names of all operators in the workspace. 
Syntax Ze A_OPS 


Z isa matrix containing all operators in the workspace. 


Usage Notes 
Z displays the names of ali operators across the screen. 


4 _ SHOW — Show Help Panel for a Function 


Purpose To display a help panel describing how to use a particular Application Prototype 
Environment function. 


Syntax &_SHOW P 
F is an Application Prototype Environment function name. 
Example 4 SHOW 'SMOD' 


Result A help panel describing SMOD is displayed. 
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A_STOP 


A_STOP — Stop Program Execution 


Purpose To set or query the stop vectors in the workspace. 
Syntax 2+ (VJ) A_STOP N 
N is a name list of functions and/or operators. 


V isan optional value. If V is omitted, A_STOP reports the settings of the stop vectors 
for the names in the list. 


Z contains the stop vectors. 
Example '' A_STOP OWL 3 4 


Result Resets all stop vectors to empty. 


Usage Notes 
The values in V will be set to the stop vector of the 
functions/operators named on the right. 


Scalar extension works in both directions with one name in the name 
list considered a unity. 
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A_TME 


A_TME — Measure Execution Time 


Purpose To measure the time (in milliseconds) used by the processor unit to execute an expression. 
Syntax Z + [N] A_TME E 

E is the expression to be timed. 

N specifies the number of times the expression is to be executed. Default is one. 


Example 12 A_TME 'A+2+2' 
008333333333 


Result The expression is executed and the time used by the processor unit is reported. The result of 
the expression is not displayed because it was assigned to a variable. 


Usage Notes 
The expression is executed the number of times specified and the 
average time used by the processor unit for one execution is 
reported. If the expression produces any result, then the result will 
be displayed N times. To avoid displaying information, the result can 
be assigned to a variable, as done in the above example. 
A- STRIP 


Syntax : 5a konnan j Y ola 29.083 
wa (AP 100" ser 
' pmnan Voklow w „nai 
E en wert ee Mond mee l 


Fkt- Nirman 


M Malik vm ra 


166 


A_TRACE and A_VARS 


A_TRACE — Set Trace 


Purpose To set or query the trace vectors in the workspace. 
Syntax Z + [V] A_TRACE N 
N is a name list of functions and/or operators. 


V isan optional value. If V is omitted, A_ TRACE reports the setting of the trace 
vectors for the names in the list. 


Z contains the trace vectors. 
Example 1 A_TRACE 'F'QONL 3 


Result Sets a trace on line 1 for all functions beginning with the letter F. 


Usage Notes 
The values in V will be set to the trace vector of the functions or 
operators named on the right. 


Scalar extension works in both directions, with one name in the name 
list considered a unity. 


4_VARS — Display Variables 


Purpose Displays the names of all variables. 
Syntax Z + A_VARS 


Z is a matrix containing all variables in the workspace. 


Usage Notes 
Z displays the names of all variables across the screen. 
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Chapter 8. Utility Functions 


The utility functions are intended to be used primarily in APL 
application functions. 
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UTILS and A_BRF 


UTILS — Show Utility Functions 


Purpose To display a list of available utility functions. 
Syntax. UTILS 


Usage Notes 
The list includes a short description of each of the utility functions. For 
more information, use the SHOW command or the PF 10 key against 
any of the functions in the list. 


A_BRF — Break First 


Purpose The Break First function finds each first element of an equal subset within an array. 
Syntax Z<A&_BRE A 

A is any array. 

Z is a Boolean vector. 


Example A_BRF 'ABCCDEFGGGH' 
Ved Os S: PE: SAS: O Oe Oy 


Usage Notes 
A Boolean array is returned containing a 1 for the first element of 
each equal subset within an array; al! other elements in the array are 
indicated by a 0. 
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A_BRL and A_BX 


4_BRL — Break Last 


Purpose The Break Last function finds each last element of an equal subset within an array. 
Syntax Z*A_BRL A 

A is any array. 

Z isa Boolean vector. 


Example A_BRL 'ABCCDEFGGGH' 
Nai © Dal Hes ea La i TEA 


Usage Notes 
A Boolean array is returned containing a 1 for the last element of 
each equal subset within an array; all other elements in the array are 
indicated by a 0. 


A_BX — Create a Matrix 


Purpose The Box function converts an argument list to a matrix. 
Syntax Z+[S] A_BX A 
Z is a matrix 
A is one of the following: 
1. a simple array of any shape or data type, or 
2. a vector of vectors. 
S (optional) is one or more separator characters. 
Example 4_BX 'Joe Smith' ‘Mary Taylor’ 


Joe Smith 
Mary Taylor 


Usage Notes 
A matrix is created from the argument list present in A. 
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AC 


Without a Left Argument Specified 


If present in A, the new-line control character (OTC{ 2 ]) will be used 
as a separator character; if O7C([ 2] is not present in A, blanks, 
commas, and slashes are all used as separators. 


S_BX 'Joe/Smith,Mary Taylor’ 
Joe 
Smith 
Mary 
Taylor 


With a Left Argument Specified 


If the right argument A is numeric, a separator character must be 
specified in S. 


If the teft argument S is specified but does not include a blank, any 
blanks in the right argument A will not be treated as separator 
characters. This can be seen in the following example: 


*,! BBX ‘Joe Smith, Mary Taylor, Cathy Jones! 
Joe Smith 
Mary Taylor 
Cathy Jones 


A_C — Compress/Replicate 


Purpose The Compress function enables operators to be used on the compress/replicate (/) 
primitive. 
Syntax Z«L ACR 
L and R contain valid data for the compress/replicate (/) primitive. 
Example (1.0 1)€1 11 0 1) 4_C” "ABC! ‘ABCDE! 
AC ABCE 
Usage Notes 


Operators such as “ (Each) can be used with A_C, as shown in the 


above examplie. 
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A_CMD 


A _CMD — Test Commands 


Purpose The Command function tests for a valid, abbreviated command in a command list. 
Syntax Z+M A_CMD C 

C is a command to be tested. 

M isa list of valid commands. 


Z isa Boolean vector containing a | for each valid command, and a 0 otherwise. 


Example "SHOW SHOWPAGE SHOWPRINT' A_CMD 'SHOWPA' 
010 
"SHOW SHOWPAGE SHOWPRINT' A_CMD 'SHOW' 
100 
"SHOW SHOWPRINT SHOWPRICE' A_CMD 'SHOWPR' 
011 
Usage Notes 


The command Ç is compared to each name in the list M. The 
comparison checks whether the command € is a valid, abbreviated 
form of the command(s) in M. If the Boolean result is all zeros, there 
is no valid hit. If the result contains a single 1, the abbreviation is 
unique. (Here, an abbreviation means that one or more characters 
have been dropped from the right.) 


The following example shows how the A_CMD function can be used 
within an APL function: 


>(1=Y++/X-M A_CMD C)/OK a 1 hit 
+(0=¥)/NOHIT a No hits 


+NOTUNIQUE a Several hits 
OK: COMMAND + X/M a Complete command 
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A_DLTC 


A_DLTC — Delete Leading and Trailing Characters 


Purpose To delete leading and trailing characters or numbers in arrays. 
Syntax Z+{C] A_DLTC A 

A isan array of any shape or rank. 

C is one or more characters or numbers. 


Example ',' A DLTC '...CHRISTIAN ... ALAN...' 
CHRISTIAN ... ALAN 


Usage Notes 
The result Z has the same rank and data type as A with all leading 
and trailing elements removed along the last dimension. If the 
optional argument Ç is not specified, blanks or zeros are removed 
from A. Otherwise, the elements to be removed are specified in C. 
The first element in C will be used as the fill element where one is 
needed. 
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4_DMB and A_DMC 


A_DMB — Delete Multiple Blanks 


Purpose To delete multiple blanks in a character vector. 
Syntax Z+ A_DMB A 
A is a character vector. 
Example A+ 'BILL SUSAN i 
B + A_DMB A 
tel, B, te! 
*BILL SUSAN* 
Usage Notes 


Multiple blanks are removed from the character vector A; that is, each 
string of multiple blanks within the character vector is reduced to a 
single blank character. In addition, leading and trailing blanks are 
removed. 


A_DMC — Delete Multiple Characters 


Purpose To delete multiple characters or numbers in an array of any shape. 
Syntax Z*EC] A_DMC A 
A isan array of any shape and data type. 
C (optional) is scalar or vector specifying the characters to be eliminated. 
Example ':,' A ONC 'Name::: Smith,, John,,,' 
Name: Smith, John 
Usage Notes 


Multiple characters, as well as leading and trailing characters or 
numbers, are removed from the array A. If the optional argument C is 
not specified, blanks or zeros are removed. Otherwise, the elements 
to be removed are specified in C. The first element in C is used as 
the fill element where one is needed. 
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A_DOC 


A_DOC — Document an Object 


Purpose To display a matrix in a format that is suitable, for example, for sending to a printer. 
Syntax Ze A_DOC 0 
O isa list of object names. Each name must be prefixed by its object type and a colon. 
The valid object types are: 
A = menu application M = menu 
cC = chart O = APL operator 
D = file declaration P = panel 
F = APL function Q = query 
I = image V = APL variable 
L = list 
Z isa character matrix that can be sent to a printer. 
Example 4 DOC 'P:MINFO' 
Result The panel MIN FO is displayed in the session manager. Using the session manager COPY 
command, it is then possible to copy the panel image to a file for purposes of printing. 
Usage Notes 


A matrix suitable to be sent to a printer is returned. 
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A_DRP and A_DTB 


A_DRP — Drop 
Purpose To drop along the last dimension of an array. 
Syntax Z+[C] S_DRP A 
A is an array of any shape. 
© is an optional control character or number. The default is a blank. 
Example A_DRP ‘COPY MYNAME DATA (OPT1 OPT2' 
MYNAME DATA (OPT1 OPT2 
"(' A _DRP ‘COPY MYNAME DATA (OPT1 OPT2' 
OPT1 OPT2 
Usage Notes 


All elements up to and including the first element equal to the control 
character are dropped. Thus, if the right argument has a blank in the 
first position, the result will be empty. If C is not specified, all 
elements up to the first blank are dropped. Leading blanks are not 
dropped. If, for example, A is left aligned and C is not specified, this 
function will drop the first word in a sentence and leave the rest 
intact. This can be useful in parsing input. 


A_DTB — Delete Trailing Blanks in Vectors 


Purpose To delete trailing blanks in a character vector. 
Syntax Z+ A_DTB A 
A is a character vector. 
Example A + ‘Christian Holter 
B + A_DTB A 
tet Bye 
*Christian Holter* 


Usage Notes 


All trailing blanks are removed. 


unchanged. 


Leading and imbedded blanks remain 
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A_DTC 


A_DTC — Delete Trailing Characters in Arrays 


Purpose To delete trailing characters or numbers. 
Syntax Z+[C] A_DTC A 
A isan array of any shape and data type. 
C is an optional character or number. 


Z has the same shape and data type as A. 


Example 'S' A_DTC 'JOE SMITHSSSS' 
JOE SMITH 
Example (0 9) 4.p7C 7869990099 
786 
Usage Notes 


Trailing elements are removed. The optional left argument can be one 
or more characters or numbers to be deleted. 
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A_E and A_ELA 


A_E — Expand Function 


Purpose 


Syntax 


Example 


The Expand function enables operators to be used on the expand primitive (X). 
ZL AER 
L and R contain valid data for the expand primitive. 


(1 0 1) (1110 1) A_E” 'AB' 'ABCD' 
A B ABC D 


Usage Notes 


Operators such as ” (Each) can be used, as shown in the above 
example. 


A_ELA — Each on Left Operator 


Purpose 


Syntax 


Example 


The Each on Left operator applies a function between each of the items on the left and the 
argument on the right. 


Z«L F A_ELA R 
Lis an array. 

F isa function. 

R isan array. 


(2 2 3)(4 3)(2 6) p A_ELA 112 
2.°3 1 3 1 2 3 4 5 6 
5 6 4 6 71 8 9 10 11 12 
7 g 
7 8 9 10 2 
10 11 12 


Usage Notes 


The function F is applied repeatediy between the right argument R 
and each of the items in the left argument L. 
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A_ERA 


A _ERA — Each on Right Operator 


Purpose The Each on Right operator applies a function between each of the items on the right and 
the argument on the left. 


Syntax ZL F A_ERA R 


L 
P 
R 


Example 


FF 


Usage Notes 


is an array. 


is a function. 


is an array. 


The function F is applied repeatedly between the left argument L and 
each of the items in the right argument R. 
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A_GRD 


A_GRD — Grade (Give Sorted Index) 


Purpose 


Syntax 


Example 


Usage Notes 


The Grade function gives the sorted index along the first dimension of any array. 
ZEC] A_GRD M 

M isan array of any shape and data type. 

C (optional) is a control character. 

Z isthe graded index on M. 


NAMES + A_BX ‘TAYLOR ASCOT SMITH! 
A_GRD NAMES 

231 
NAMESTA_GRD NAMES; ] 

ASCOT 

SMITH 

TAYLOR 


The result Z contains the sorted index of M. To sort M, Z can be used 
as an index on the first dimension of M. The sorted index is ascending 
unless the optional left argument Ç is a negative number, in which 
case the order is descending. If C is an alphabet, that alphabet will 


be used for ordering (rather than the system default alphabet). If C is 
0, no grading is done, 
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A_HLT and A_HOST 


A_HLT — Halt Execution Temporarily 


Purpose To halt execution temporarily. 


Syntax A_HLT 


Usage Notes 


Temporarily halts execution so that a stacked expression can be 
executed. When the execution stack is empty, normal program 
execution continues. The A_HZT function inserts a continue 
expression at the end of the stack to ensure that the program 
resumes after execution of the stacked expressions. 


For related information, see the description of the A_QUE function 
on page 195. 


A_HOST — Host Command 


Purpose To send commands to the host system for execution. 
Syntax Z + A_HOST E 

E is any valid host command. 

Z isthe retum code from the host system. 
Example A + A_HOST ‘QUERY READERLIST' 


Result The command QUERY READERLIST is sent to the host system for execution. 


Usage Notes 
The command is sent to the host system for execution. The return 
code depends upon the success or failure of the command as 
executed by the host system. 
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\_HOW 


4_HOW — Display Function Comments 


Purpose To provide information about a function. 
Syntax M + 4 HOW F 

F isa list of names. 

M is the information on the functions. 


Example A_HOW 'FUNCO1 PROGO2' 


Usage Notes 
Displays all comment lines in the specified function(s) that begin with 
the two characters a |. If no comment lines are found, the syntax of 
the function is displayed. 


Notes: 


1. Use the &_SHOW function to display help information for any of the 
functions in the product. 


2. When you use the LRUN function to display a list of your own 
functions, LRUN will display the first line it finds that begins with the 
two characters A |. The. A_HOW function, on the other hand, will 
display all lines in a function that begin with these characters. 
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A_INP and A_LAL 


A_INP — Input Prompt 


Purpose 


Syntax 


Example 


Result 


The Input function prompts for character data input. 
Z+A_INP T 

T isthe prompt text. 

Z isthe entry made by the user. 

A_INP ‘Enter your name:' 


The prompt is presented to the user. 


Usage Notes 


When A_INP is executed, the right-hand argument is displayed on 
the screen as a prompt to the user. Z is the answer typed by the 
user, with all unnecessary blanks removed. The first word typed by 
the user is left justified. 


A_LAL — Left Align 


Purpose The Left Align function aligns an array on the left margin. 
Syntax Z+[C] A_LAL A 
A is any array. 
C (optional) is one or more justification elements 
Z is an array, of same shape as A, which is aligned on the left margin. 
Example tot A_ LAL teccceSQME TEXT' 
SOME TEXTococce 
Usage Notes 


All elements in A are justified to the left. Blanks or zeros are used as 
control characters unless overridden by the optional left argument C. 


C may contain one or more elements; the first element in C is used 
as the fill element. 
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A_LST 


A_LST — List Words in a Matrix 


Purpose The List function displays the words in a matrix across the screen. 


Syntax Z+CCJ] AL 


LST M 


M is a matrix. 


C is an optional control vector with one or two elements, as follows: 


cC1) 


CE2] 


Note: 


determines the sorting order: 

e a positive number sorts in ascending order. 

è zero gives no sort. 

© a negative number sorts in descending order. 
determines whether to sort by columns or by rows: 
è a positive number sorts by columns. 

e zero sorts by rows. 


Default for C is 0 0. 


Example (1 1) A_LSPF A_OL'P! 


Result All panels are listed on the screen, sorted by column and in descending order. 


Usage Notes 


The matrix Z is formatted in columns and rows spread out over the 


screen (using OPW as the maximum width). 
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A_MAD and A_MAR 


A_MAD — Matrix Add Downwards 


Purpose The Matrix Add Downwards function combines two matrices, one on top of the other. 
Syntax ZL & MAD R 
Land R are both arrays of maximum rank 2. 
Example At 2 2p'AAAA' 
B+ 3 3p'BBBBBBBBB' 
A A_MAD B 
AA 
AA 
BBB 
BBB 
BBB 
Usage Notes 


The result is a matrix with the contents of R placed as rows below L. 
The width is adjusted to the widest of the two arrays. 


A_MAR — Matrix Add Repeated 


Purpose 


Syntax 


Example 


The Matrix Add Repeated function combines two matrices, one next to the other, with rows 
repeated as needed. 


Z+L A_MAR R 
L and R are arrays of maximum rank 2. 


A + 2 2p'AA' 
B + 3 3p'BBB' 
A A_ MAR B 

AABBB 

AABBB 

AABBB 


Usage Notes 


The result is a matrix with the contents of R placed to the right of L. 
The number of columns is the sum of the columns in Z and R. The 
number of rows is determined by the longer array. Columns and rows 
of L and R are repeated as needed to fill the shape of Z. 
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A_MAS and A_MM 


A_MAS — Matrix Add Sideways 


Purpose The Matrix Add Sideways function combines two matrices, one next to the other. 
Syntax ZeL A_MAS R 
Land R are arrays of maximum rank 2. 
Example Le 2 2p'AA' 
Re 3 3p'BBB' 
Z+ L A MAS R 
AABBB 
AABBB 
BBB 
Usage Notes 


The result is a matrix with the contents of R placed to the right of L. 
The number of columns is the sum of the columns in L and R. The 
number of rows is determined by the longer array. 


A _MM — Matrix Membership 


Purpose The Matrix Membership function indicates the rows in one matrix that are found in another 
matrix. 
Syntax 2+« L A_MMR 
L and R are arrays of maximum rank two. 
Example L+ 2 2p'ACAB' 
Re 2 2p'BAAB' 
L AMM R 
01 
Usage Notes 


The result is the same as for the APL Member (e€) function with the 
added feature that matrices may be specified as left and right 
arguments. The Boolean result contains a 1 for each element found in 
the other matrix and a 0 otherwise. 
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A_MMI 


A _MMT — Matrix-to-Matrix Index 


Purpose The Matrix-to-Matrix Index function gives the indices of rows in one matrix that are found 
in another matrix. 
Syntax Z<«L A_MMI R 
DLandk&k are arrays of maximum rank two. 
Example L+ 3 3p 'ABCQQQXYZ' 
Re 3 3p'ABCTITXY2' 
L A_MMI R 
143 
Usage Notes 


The A_MMT function works on matrices in the same way the APL iota 
(1) primitive works on vectors. It yields, for each row in R, the row 
number of the first matching row in L. 


If a matching row is not found in Z, the number returned is one 
greater than the number of rows in L. 
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A_MSL 


A_MSL — Matrix Select 


Purpose The Matrix Select function gives a Boolean selection expression from a matrix of names. 
Syntax Z-S A_ MSL M 

M isa character matrix. 

S isa selection specification where an asterisk represents zero or more letters. 


Z is a Boolean vector that can be used to select the rows in M that satisfy the selection 
specification in S. 


Example A LST ('*ABC*' A_MSL MAT)#MAT 


Result All rows containing the letters ABC are selected from the matrix MAT and then listed across 
the screen. 
Usage Notes 


An asterisk in the selection expression allows you to select all names 
containing a specified letter combination. The Boolean result of 
A_MSL indicates (with ones) all the rows that conform to the 
selection criteria. 


Chapter 8. Utility Functions 189 


A_M2VV 


A_M2VV — Matrix to Vector-of-Vectors 


Purpose The Matrix to Vector-of- Vectors function converts a matrix to a vector of vectors and 
deletes trailing blanks on each individual vector. 

Syntax Ze A_M2VV M 
M isa character matrix. 
Z isa vector of vectors with trailing blanks removed. 

Example S_M2VV 2 3p'ABCDEF' 
ABC DEF 

Usage Notes 


The specified matrix is converted to a vector of vectors that contains 
one element for each row of the matrix. The trailing blanks of each 
element are removed. 


Note: \f you are not concerned about trailing blanks, then the idiom 
c[2]M is faster than the A_M2VV function. 
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A_NLT 


A_NLT — National Language Translation 


Purpose 


Syntax. 


Example 
Result 
Example 


Result 


The National Language Translation function switches the national language during 
execution and optionally converts characters to upper case. 


Z + ALNLT L 
L might be one of the following: 
© empty — the current language is queried. 
e an available language (for example, ' DEUTSCH '). 
© the character O or 1: 
~ 1l displays all text and panels in upper case. 
— 0 displays all text and panels in mixed case. 
e an available language and either of the characters 0 or 1. 
Z is the current language after execution. 
A_NLP '' 
Queries which language is being used. 
O_NLT '1 SVENSKA! 


Switches to Swedish and converts all text to upper case. 
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A_0C 


A_OC — Object Classes 


Purpose The Object Classes function gives the object classes of the names in a list. 
Syntax Z+[L] A_OC N 
N isa list of names. 
L is an optional switch: 
0 (default) returns only a bit matrix. 
1 returns a bit matrix with headings for each column and names for each row. 
Example 1 4_0OC NAMELIST 
oVFOACDILMP® 
VARI 010000000000 
s 100000000000 
FUNC1 001000000000 
PAN1 000000000010 
IMAGE1 000000010000 
Result The second object in NAMELIST is an invalid object; all the other objects are valid. The 
first object (VAR1) is a variable, the third object (FUNC1) is a function, the fourth object 
(PAN 1) is a panel, and the fifth object (TMAGE1) is an image. 
Usage Notes 


The result is a bit matrix indicating the object classification of each 
name in the list. For each object, a 1 appears in the column 
corresponding to its object class. Column 1 indicates if the name is 
valid as an object name in Application Prototype Environment. For 
more information on object types and naming conventions, see 
Chapter 1, “Introduction” on page 1. 


The columns in the bit matrix are as follows: 


A = menu application M = menu 
C = chart © = APL operator 
D = file declaration P = panel 
F = API, function Q = query 
Z = image V = APL variable 
L list e = invalid name 
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A 


_OL 


A_OL — Object List 


Purpose The Object List function produces a matrix of object names, prefixed by the individual 
object types. 


Syntax Ze [L] 4_OL R 


R 
L 
Example 
P 
P 
I 
M 
Usage Notes 


is a list 


of one or more object types. 


is an optional type/name separator. 


Ze A_OL 'PIM' 


:MINFO 

:MYPANE. 
:MYIMAG 
:MYMENU 


L 
E 


The result is a list of names belonging to the object types specified in 


R. Each object in the list is prefixed by an object type and a colon. 


You can replace the colon with a different separator by specifying a 


value for L. 


Valid object types are: 


menu application 
chart 

file declaration 
APL function 
image 

list 


Ce 


PHM OOD 


COU0E 


ee 


menu 
APL operator 
panel 
query 
APL variable 
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A_PLA and A_PRA 


A_PLA — Pervasive on Left 


Purpose The Pervasive on Left operator applies a function between each simple array on the left and 
the argument on the right. 


Syntax ZL F A_PLA R 
L isan array. 
F isa function. 
R isan array. 


Example 1 ¢ Jp A_PLAI6 
1 


23 
1. 2.:3 
45 6 


Usage Notes 
The function F is applied repeatedly between each of the simple 
arrays in Z and the right argument. 


A_PRA — Pervasive on Right 


Purpose The Pervasive on Right operator applies a function between each simple array on the right 
and the argument on the left. 


Syntax Z+L F ' PRA R 
L is an array. 
F isa function. 
R is an array. 


Example 3pA_PRA 1,¢2,¢3 4 
e eae a Se em a 


Usage Notes 
The function F is applied repeatedly between each of the simple 
arrays in R and the left argument. 
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A_@Q and A_QUE 


A_QQ — Duplicate Quotes 


Purpose To duplicate all occurrences in the right argument of elements that appear in the left 
argument. 


Syntax Z + [R] 4_QQ S 
S isa vector. 


R (optional) is one or more elements in S to be duplicated. If R is not specified, the 
default is the quote character. 


Example (c'VERY') A_QQ 'A' 'VERY' 'SIMPLE' 'EXAMPLE' 
A VERY VERY SIMPLE EXAMPLE 


Usage Notes 
This function, referred to as the “double quote” function, is often used 
to double the number of quote characters needed in expressions 
intended to be used with the execute function or with strings that 
need to be sent to the host system for execution. 


A_QUE — Queue 


Purpose To stack expressions for FIFO execution. 
Syntax A_QUE E 


E işa matrix or a set of substrings separated by OTC 21], with each line or substring 
containing a command. 


Usage Notes 
Each command in Æ is stacked to be executed at the next program 
halt. If any error occurs during queuing, the entire queue is cleared, 
including any previously queued expressions. 


If Æ is 0, the existing queue is cleared. 


To cause a temporary halt during program execution, use the A_LHLT 
function after the queuing is completed. 
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A_RAL 


A_RAL — Right Align 


Purpose The Right Align function aligns an array on the right margin. 
Syntax Z+[C) A_RAL A 
A isan array. 
C (optional) is one or more justification elements. 
Z is an array, of same shape as A, which is aligned on the right margin. 
Example to' A RAL 'SOME TEXT?°90000' 
oooooSQME TEXT 
Usage Notes 


All elements in A are justified to the right. Blanks or zeros are used 
as control characters unless overridden by the optional argument C. C 
may contain one or more elements; the first element is used as the fill 
element. 
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A_REP 


A_REP — Replace 


Purpose To replace elements in an array. 
Syntax ZR A_REP § 
S is any array. 


R specifies replacement in S as follows: 
/old/new/C"] UN], where: 


$ is the separator, which can be any character not in old or new. 
old specifies the values to be replaced. 
new specifies the replacement values. 


(optional) specifies that all occurrences are to be replaced. 
N (optional) specifies that replacement is to be made by APL name only. 


Example '/XYZ/ABC/U~ JEN" A_REP 'XYZ 222 XYZ XYZX' 
ABC ZZZ ABC XYZX 


Usage Notes 


The array S is updated as specified by Æ. The separator can be any 
unique value not found in old or new. If S is numeric, then R must 
also be numeric. 


Note: The strings old and new need not be of the same length. W 
and can be specified in any order. 
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A_RM and A_RU 


A _RM — Reduce Matrix 


Purpose The Reduce Matrix function removes blank columns on the right of a matrix and blank 
rows at the bottom of a matrix. 


Syntax Z + A_RM M 
M isa matrix. 


Example MATRX + 3 8p'JOE TOM ' 

MATRX 

JOE 

TOM 
pMATRX 

38 
MATRX2 + A_RM MATRX 
MATRX2 

JOE 

TOM 
pMATRX2 

23 


Usage Notes 
All trailing blank columns and lines are removed. 


A__RU — Remove Underscores 


Purpose The Remove Underscores function removes the APL underscores in any characters. 
Syntax. Z + A RUS 

S isa character array of any dimension. 

Z is the same array with underscored characters converted to uppercase characters. 
Example VAR + ‘SUSAN JONES ___* 


A_RU VAR 
SUSAN JONES 


Usage Notes 
Any APL underscore characters are converted to normal uppercase 
characters. 
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A_SET 


A_SET — Set or Query Workspace Controls 


Purpose To set control of various operations in the product. 


Syntax Z + K &_SET V 


K 


Z 


the keyword, is a character vector for specifying one of the following: 
CURRENT sets panel modification mode ON/OFF. 
DEBUG sets system debug mode ON/OFF. 
ENVIRON sets environment to CMS/TSO. 
EXPAND sets panel expansion ON/OFF. 
IDENTIFY sets message identifiers ON/OFF. 
LIBMSG sets automatic library messages ON/OFF. 
NULLS sets NULLS ON/OFF. 

NUMACCEPT sets panel camer control ON/OFF. 
PAGING sets GDDM paging ON/OFF. 
SPRIXIMCG sets fonts for SPRIX. 


the value, controls the setting of the keyword argument. It can be one of the 
following: 


ON or 1 to activate the switch for the specified keyword. 
OFF or O to deactivate the switch for the specified keyword. 


value that is, a special value as specified for each of the keywords described on the 
following pages. 


Note: For the SPRIXIMG keyword, the value V is a name that identifies the image 
symbols or the symbol sets to be used. 


reports the current setting of A_SET. 


Example ‘IDENTIFY' A_SET 1 


Usage Notes 


The option selected by the keyword K set according to the value in V. 
The setting is always reported; thus, if V is empty, A_SET will work 
as a query function. 


Note that the keyword KX can be abbreviated by dropping letters from 
the right as lang as the remaining characters are unique among the 
other keywords. However, it is recommended that you use the 
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4_SET — CURRENT 


complete keyword name in case the addition of new keywords in 
future releases causes a particular abbreviation to become invalid. 


Individual help panels are provided for each of the keywords; to view 
these help panels, use the A_SHOW function with the complete name 
of one of the keywords as the right argument. 


See the descriptions of the individual keywords on the following 
pages for the actions produced by the specific setting of V. 


CURRENT — Set Panel Modification 


Purpose To honor dynamic panel changes only on the current panel when it is redisplayed; or, only 
on the next panel that is displayed (even if it is a new panel). 


Syntax ‘CURRENT’ A_SET V 
V the values for V are: 


ON or 1 panel modifications are honored only if the next panel displayed is the 
current panel. 


OFF or 0 (default) panel modifications are honored on the next panel that is 
displayed. This is the default. 


Usage Notes 
The functions which are used to modify panets are: 


SCUR 
SCOL 
SHLT 
SPSS 
STYP 
SWRI 


oeeveee 


When you use these functions for modifying panels, the values 
specified are saved in a modification stack until a new panel display 
is initiated. If the CURRENT keyword has been set to ON, the stack is 
cleared when a new panel is initiated. If CURRENT is setto OFF, 
the stack is not cleared and the system wil! attempt to insert the 
values from the stack into the new panel. 


Note: The SCLEAR function always clears the stack. 
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A_SET — DEBUG 


DEBUG — Debug Mode 


Purpose To control error handling. 


Syntax Ze 
Vv 


Usage Notes 


'DEBUG' & SET V 
the values for V are: 


ON or 1 In case of errors, execution is terminated at the point of error; you may then 


attempt to fix the problem. You can use ) SJ to display your suspended 
functions and to examine local variables. 


OFF or 0 In case of errors, execution is terminated and an error message is displayed. 


This is the default. 


reports the current debug mode. 


if any errors occur, the actions performed by the product are 
determined by the DEBUG switch. When debugging your own 
functions that are called by system operations (for example, execution 
of menus and lists), execution will be halted at the point of error if the 
DEBUG switch is set to ON or 1. If the switch is set to OFF, the 
system will trap the error and issue an error message. 


When DEBUG is ON, expressions are executed directly using the 
APL primitive function #. Thus, APL will stop execution at the point of 
error, or at the point where the user code has any error protection. 


Note: If you can correct the error, then you may continue execution 
of your program by branching to the line counter (+0ZC). Do not 
attempt to start execution from the beginning again without clearing 
the stack with + or )RESET. 


If an error is reported by AP 126, the message is issued with the 
function SCHK shown as the source. The actual description of the 
error messages from the auxiliary processors can be found in the 
appropriate APL2 publication or in the GDDM: User's Guide. If 
feasible, the FSQERR call is issued to GDDM to get the explanation. 


If DEBUG mode is set to ON or 1, you can investigate the actual 
GDOM return codes. 


GDDM. This variable is not reset for every successful operation; 
however, the message is time-stamped when the GDDM message is 
received. 


Chapter 8. Utility Functions 201 


4_SET — ENVIRON 


ENVIRON — Operating Environment 


To initiate or query the operating environment (either CMS or TSO). 


Purpose 
Syntax Ze 
Vv 
Z 
Usage Notes 


'ENVIRON' A_SET V 
the values for V are: 
CMS sets the CMS operating environment. 
Tso sets the TSO operating environment. 
reports the current environment: 
2 for CMS. 


3 for TSO. 


This function is used at installation time, or when you want to transfer 
an application workspace from one environment to another. 


If you transfer a workspace between operating environments, you 
must use the ENVIRON keyword of the A_ SET function before 
performing environment dependent operations such as gaining access 
to files or libraries. 


You may use this keyword to test the operating environment if your 
application is not limited to running in one environment. For exampie: 


+(2 3='"ENVIRON' A_SET '')/CMS,TSO 
O+'Environment unknown’ 
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A_SET — EXPAND and IDENTIFY 


EXPAND — Expand Panels 


Purpose To control how a panel is expanded to fit on to a screen that is larger than the one for 
which it was originally designed. 


Syntax. "EXPAND' A_SET V 
V The values for V are: 
ON or 1 panels are expanded. This is the default setting. 


OFF or O panels are not expanded. 


Usage Notes 


Panels designed for a standard screen size (for example, 24 or 32 
lines) are automatically expanded to fill the surface of a larger screen. 


IDENTIFY — Identify Messages 


Purpose To control the display of message identifiers. 
Syntax Z + 'IDENTIFY' A_SET V 
V The values for V are: 
ON or 1 message identifiers are displayed. 


OFF or 0 message identifiers are not displayed. This is the default. 
Z reports the IDENTIFY mode. 


Usage Notes 


If the IDENTIFY keyword is set to OW or 1, a mėssage identifier in 


the following form will be displayed at the beginning of each 
message: 


FFFF-ITI where 
FFFF isthe name of a system function. 


LT, is the local ID of the message. 
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A_SET — LIBMSG 


LIBMSG — Control Library Messages 


Purpose To turn automatic library message display on or off. 
Syntax "LIBMSG' &_SET V 
4 : the values for V are: 
ON or 1 to display library messages. 


OFF or 0 to not display library messages. 


Usage Notes 
When you perform library access from within your application 
functions, you will normally not want any interference from library 
messages; you should then set LIBMSG to OFF or 0. Your code 
must still check ORC and QRC2, however. 


During application development, when you are using the object library 
in the session manager, it might be convenient to have the library 
messages displayed automatically. You would then set LIBMSG to 
ON or 1. 
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A_SET — NULLS and NUMACCEPT 


NULLS — NULLS Control 


Purpose To set trailing blanks to nulls or blanks. 
Syntax Z + 'NULLS' A_SET V 
V the values for V are: 
ON or 1 sets trailing blanks to nulls. 
OFF or O sets trailing blanks to blanks. 


Z reports the NULLS mode (1 or 0). 


Usage Notes 
To query the current setting, specify V as an empty right argument. 


A setting with trailing nulls allows the use of the INSERT key. 


NUMACCEPT — Numeric Acceptance 


Purpose To control the checking and correcting of numeric input data from a panel. 
Syntax Z + 'NUMACCEPT' A _SET V 
V the values for V are: 


ON or 1 input data is accepted and converted to numeric data in the workspace. If 
the data is completely invalid (as for example ' ABC '), the variable in the 
workspace will receive a value of zero. If the input includes numeric data, 
the first numeric string will be used. For example, '12 ABC 67' would 
be interpreted as the number 12. 


OFF or 0 No invalid input is accepted. Invalid data will not update the corresponding 
variable in the workspace. 


Z reports the current setting of NUMACCEPT. 


Usage Notes 


Valid numeric input conforms to the rutes for APL numeric data. For 
further information, see SYUMRC on page 67. 
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A_SET — PAGING 


PAGING — Control GDDM Paging 


i Purpose To use GDDM paging facilities to improve response time. i 


Syntax Z< 


i d 


Usage Notes 


'PAGING' A_SET V 


the values for V are: 


a positive integer 


zero 


empty 


A set of GDDM pages will be initiated. Each new panel will use a new 
page until all pages have been used. If a previously displayed panel is 
displayed again, the GDDM page saved for that panel will be reused, thus 
resulting in improved performance. Any panel modifications done earlier 
are retained. 


This will reset the stack and release the GDDM pages. 


This will give you the paging table, if one exists. 


a matrix of panel names. 


A set of GDDM pages will be initiated, one for each panel in the matrix. 
These pages will be used whenever the particular panel is displayed. The 
page will be initiated the first time a panel is used. 


is the number of GDDM pages initiated; or, it is the paging table. 


When you use GDDM paging, a table is created that contains the 
following: 


e the names of the panels that have associated pages 
è the GDDM page number 


e a number indicating how many times the panel has been called as 
a “new” panel. 


When you use paging you save on execution time but use more 
storage. If you do not know exactly which panels your user will 
display most often, you can initiate the paging stack with a number 
and let the user run the application for a while. When you then 
display the table, you can see which panels were used most 
frequently. You may then have enough information to initiate the 
Paging stack using a name list rather than a number. 
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4_SET — SPRIXIMG 


SPRIXIMG — SPRIX Image Symbol Set 


Purpose To set or query the image symbol sets to be used for the SPRIX graphical function. 
! Syntax Z + 'SPRIXIMG' &_SET V 
V The values for V are: 


e two names of image symbol sets to replace the names APL2ISSC and 
ADMDVSS, respectively, or 


e a question mark (?) to query the setting, or 


e an empty vector to reset the symbol set names to the system default. 


Z reports the setting of SPRIXIMG. 


Usage Notes 
Controls which image and vector symbol sets are used. This keyword 
thus allows you to replace the default image symbols (APL2ISSC and 
ADMDVSS). To restore the defaults, you specify V as an empty vector. 


You might use the SPRIXIMG parameter, for instance, to use symbol 
sets that provide national language characters. 


A question mark will show the current setting. 


For more information, see SPRIX on page 71. 
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A_SHP 


A __SHP — Shape of Variables 


Purpose To display the shape of nested arrays. 
Syntax Z+[C] A_SHP A 
A is any array. 
C (optional) controls the display format: 
0 displays across the screen. 
1 (default) displays downwards on the screen. 


Z contains numbers to indicate the shape of each array; or, the Jot (°) symbol for each 
scalar. The letters and C represent numeric and character data, respectively. 


Example A_SHP 2 2 p'ONE' 'TWO' 1111 22 


Depth 2; 3 element character vector 
Same as previous row 

Depth 2; scalar numeric 

Same as previous row 


DDDD 


|- 
13 e 
j3 c 
jo N 
lew 


Usage Notes 
The shape of a variable is displayed vertically, as in the above 
example, if room is available on the screen; otherwise, it is shown 
across the screen. When displayed horizontally, all information must 
then be read from top to bottom. For instance, a character matrix of 
shape 2 3 appears as follows when it is displayed horizontally: 


2 
3 
C 


The characters have the following meanings: 


c character data 
N numeric data 
° scalar 

€ empty. 

a number 


the shape of the array. 
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4_SMGR 


You may want to use the A_SHP function for large variables that 
would produce too much output if displayed with the A_DSPLY 
function. For small variables, the A_DSPLY function produces a 
graphical illustration that is very informative. 


You can control how information is displayed with the optional 
parameter C. 


A_SHP displays the shape of nested variables down to each simple 
element. 


A_SMGR — Session Manager Command 


Purpose To issue commands to the session manager. 
Syntax Z4A &_SMGR C 
C is a character vector containing a session manager command. 
A isa switch setting the actions following an error: 
t any error return codes are retumed in Z. 
O an appropriate error message is issued and processing is terminated according to 


the setting of the DEBUG mode as set by the A_ SET function. 
Example 1 A_SMCR ‘PAGE +1" 


Usage Notes 
The command C is executed by the session manager. 
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A_SRT 


A_SRT — Sort 
Purpose To sort a character matrix. 
Syntax Z+[C] S_SRT M 
M isa matrix to be sorted. 
C isan optional control character determining the sort order: 
e a positive number or an empty value results in an ascending sort sequence. 
e zero results in no sorting. 
e a negative number results in a descending sort sequence. 
© a character string establishes the alphabetic sorting order. 
Z isthe sorted matrix. 
Example “1 O_SRT 3 4p'ABCDEFGHISKL' 
IJKL 
EFGH 
ABCD 
Usage Notes 


The matrix is sorted in ascending order if C is a positive number, 
and in descending order if a negative number is supplied for C. If C 
is a character string, that string will be used as the alphabetic order 
for sorting. If M is numeric and C is character, C is ignored. 
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A_TE — Time Edit 


Purpose The Time Edit function formats a numeric variable to character-date format. 
Syntax Z+a_TE T 


T isa numeric vector containing the date and time in the same format as returned by 
ars. 


Example S_TE 1986 6 28 18 15 
86-06-28 18:15 


Usage Notes 
Results in a character vector containing the formatted date and time 
from T. This is a convenient way to edit the result of OTS. 


The time is edited according to the usage in the national language in 
which the system is being run, 


The format of the numeric variable 7 must be: 


year month day minutes seconds ... 
Only the first five values of 7 are used. 


If you want the editing of the date to be different, you may want to edit 
this function. 
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A_TKE and A_TS 


A_TKE — Take 
Purpose To take along the last dimension of any array. 
Syntax Z+[C] A_TKE A 
A isan array of any shape. 
C (optional) is an control character or number. The default is a blank. 
Example S_TKE 'COPY MYNAME DATA (OPT1 OPT2' 
COPY 
'(' A_TKE ‘COPY MYNAME DATA (OPT1 OPT2' 
COPY MYNAME DATA 
Usage Notes 


All elements up to, but not including, the first element equal to the 
control character are selected (taken). If C is not specified, all 
elements up to the first blank are taken. 


Note: If A is left aligned, the A_TKE function will take the first word 
in a sentence and leave the remainder intact. This can be useful in 
parsing input. 


A_TS — Time Stamp 


Purpose The Time Stamp function displays the edited date and time. 


Syntax 


Zed _TS 


Usage Notes 


Results in a character vector containing the edited date and time. 


Editing is done according to the usage in the national language in 
which the system is being run, If you want to change the format of 
time-stamp information, you can edit A_TE. 
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_uC 


A_UC — Upper Case 


Purpose The Upper Case function converts all lowercase characters to upper case. 


Syntax Z«A_UC S 
S isa character array of any dimension. 


Z has the same as S$ with all characters converted to upper case. 


Example NAME + ‘joe smith! 
4_UC NAME 
JOE SMITH 
Usage Notes 


The character array is converted to upper case. 
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A_UNIQ 


A_UNTQ — Unique 


Purpose The Unique function returns the unique elements in a vector or matrix. 
Syntax Z+[C] A_UNIQ D 
D isa vector or matrix of characters or numbers. 
C (optional) specifies the sort order: 
© a positive number or an empty value results in an ascending sort sequence. 
© zero results in no sorting. 
e a negative number results in a descending sort sequence. 
e a character string establishes the alphabetic sorting order. 
Z is all elements or rows in D that are unique. 
Example VAR + ‘A BBC! 
& UNIQ VAR 
ABC 
“1 A_UNIQ VAR 
CBA 
Usage Notes 


Results in all unique elements or rows in D. The optional left 
argument C specifies a sorting order. If C is a positive number or is 
omitted, the sorting order is ascending; if negative, descending. If C 
is 0, no sort is performed. Ç can also be an alphabet, in which case 
this alphabet is used for sorting. 
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A_VNI 


A_VNI — Verify Numeric Input 


Purpose The Verify Numeric Input function checks if a character vector or matrix can be converted 
to numeric values. 


Syntax Ze[T] A_VNI D 


D işa character vector or character matrix containing values to be checked for numeric 
conversion. 


T (optional) specifies that even extended data types be recognized: 


E scientific notation 

R radian notation 

J complex number notation 
D degree notation. 


Example "J' A_VNI 'OJ1 A 25' 
101 


Usage Notes 
The result is a Boolean vector indicating whether a vector element or 
a row of a matrix can be converted to numeric values. A Boolean 
value of 1 indicates that conversion can take place; otherwise, a 0 is 
returned. 


Only character strings that can be converted to numbers by APL using 
the execute (2) function will be accepted. Thus the element might 
contain a decimal point and the APL negative sign, but the minus or 
plus sign wilt cause an error. 


If D is a vector, all elements in D are tested for validity. If Dis a 
matrix, each line is tested as one unit; as a result, a line that contains 
two elements that by themselves would be accepted will still cause an 
error. 
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A_voc 


A_VOC — Verify Object Class 


Purpose The Verify Object Class function verifies that named objects are present in the workspace. 
Syntax Ze A_VOC N 
N isa list of object names, prefixed by the object-type letter of the object (P: for panels, 
and so on). 
Z isa Boolean vector with 1 for each name in N belonging to the class letter indicated 
and 0 otherwise. 
Example A_VOC 'P:PANO1 M:MENUOL' 
i iH / &_VOC OINDEX 'LIB! 
Usage Notes 


The Boolean result in the first exampte indicates that the panel 
PAWN01 is present in the workspace whereas the menu MENU01 is 
not. The second example verifies that all objects in library LIB are 
present in the workspace. 
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CDROP 


CDROP — Drop System Components 


Purpose To remove one or more of the system components when not needed. 
Syntax CDROP C 
C is the name list of system components. 


Example CDROP '‘MDESIGN PDESIGN DOCUMENT* 


Usage Notes 
The system components are removed from the workspace, thus 
providing more room for application use. When needed, these 
components can be loaded again with the CLOAD function. The 
components that might be removed are: 


CDESIGN CHARUN FDESIGN FILERUN 
IDESIGN IMAGES LDESIGN LISTRUN 
MDESIGN MENURUN ODESIGN LIBWRT 
PDESIGN PANRUN QDESIGN QUERY 
DOCUMENT DIALOG AUXILS COMPAT 


If any of the design components (for example, PDESIGN) are called, 
the necessary functions are automatically loaded. See 
ONPARMS[ 71 on page 151 for more information. 
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CLOAD and DESIGN 


CLOAD — Load System Components 


Purpose To retrieve one or more of the system components not present in the workspace. 
Syntax CLOAD C 
C isa name list of system components. 


Example CLOAD ‘MDESIGN PDESIGN DOCUMENT! 


Usage Notes 

The specified system components are loaded from the system 
libraries and made available for use. Normally the CLOAD function is 
used to retrieve components that have been removed with the 
CDROP function. The components that might be loaded are: 

CDESIGN CHARUN FDESIGN FILERUN 

IDESIGN IMAGES LDESIGN LISTRUN 

MDESIGN MENURUN ODESIGN LIBWRT 


PDESIGN PANRUN QDESIGN QUERY 
DOCUMENT DIALOG AUXILS COMPAT 


DESIGN — Display DESIGN Menu 


Purpose To display a menu containing options for calling the individual design menus. 
Syntax DESIGN 


Usage Notes 
Each of the menu options calls one of the design menus. 
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DIALOG and DOCUMENT 


DIALOG — Invoke a Menu Application 


Purpose To invoke the top menu in a menu application system. 
Syntax DIALOG A 
A is a character string containing the name of a menu application. 


Example DIALOG 'APPLICO1! 


Usage Notes 
The top menu in a menu application system is displayed and the 
entire menu system is made available to the user. 


DOCUMENT — Call DOCUMENT Menu 


Purpose To call the Documentation Tool menu. 


Syntax DOCUMENT 


Usage Notes 
Displays a menu containing options for documenting an entire 
application or selected objects within an application. 
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FUNCTIONS and IDESIGN and [LIST 


FUNCTIONS — Display FUNCTIONS Menu 


Purpose To display a menu from which you can select lists containing all the functions in the 
product. 


Syntax FUNCTIONS 


Usage Notes 
You can display help information for each of the functions in the lists. 
Another way of displaying help information for individual functions is 
to type the A_.SHOW function in the session manager followed by the 
name of a product function, as shown in the following example: 


A_SHOW 'SMOD' 


IDESIGN — Display IDESIGN Menu 


Purpose To call the Image Design menu. 
Syntax IDESIGN 


Usage Notes 
Displays a menu containing options for designing images. 


ILIST — Display List of Images 


Purpose To display a list of user-created images. 


Syntax ILIST 


Usage Notes 
You can use commands and PF keys to perform operations on the 
images in the list. Press PF 4 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 
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LANGUAGES and LDESIGN 


LANGUAGES — Switch National Languages 


Purpose To switch to another language and/or to convert text to uppercase. 


Syntax LANGUAGES 


Usage Notes 
A panel is displayed which lists the languages made available to you 
at your installation. To switch to another language, place the cursor 
alongside the desired language and press PF 11. 


A message is displayed to confirm the language switch, and from then 


on, all panels, tutorials, and messages are displayed in the selected 
language. 


LDESIGN — Display LDESIGN Menu 


Purpose To call the List Design menu. 
Syntax LDESIGN 


Usage Notes 
Displays a menu containing options for designing lists. 
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LIBCONV 


LIBCONV — Convert Libraries 


i Syntax LIBCONV 


Usage Notes 


Purpose To display a menu from which you can convert an Application Prototype Environment 
Version | library to the format for Version 2. 


Since the internal format of both object libraries and individual objects 
in Version 2 is different from the Version 1 format of Application 
Prototype Environment, you need to convert any Version 1 libraries 
and objects that you want to use in Version 2. The LIBCONV function 
displays a panel where you are prompted for the name of a Version 1 
library and for the new, Version 2 library name. It is recommended 
that you add a suffix of ‘2’ to the new library name to distinguish it 
from a Version 1 tibrary. 


During conversion, Version 1 objects are read from the old library and 
are converted to the Version 2 format before being stored in the new 
library. A status report is displayed repeatedly on the screen during 
the conversion process. 


All objects in the Version 1 library, including groups and latent 
expressions, are converted to the Version 2 format. If an object type 
code of A: is found in the Version 1 library, this code is converted to 
G: (group). In Version 2 the code A: is used to represent menu 
applications, which did not exist in Version 1. If you have a Version 1 
application that is initiated by using an object code of A: (for 
example, 'MYLIB' OGET 'A:STARTUP'), this application must 
be changed to use the code G: instead. Thus, the Version 1 4: 
object is still the same object as before — only the object type code 
that identifies it is different in Version 2. 


Note: When conversion is completed, you might want to load the 
COMPAT APELIB2 library to be able to run an application that uses 
functions that have been renamed or changed in Version 2. The 
functions in the COMPAT library have the same names and syntax as 
the corresponding functions in Version 1. 
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LLIST and LRUN 


LLIST — Display List of Lists 


Purpose To display a list of user-created lists. 
Syntax LLIST 


Usage Notes 
You can use commands and PF keys to perform operations on the 
lists in the list. Press PF 1 from the tist to display the available 
commands. You can display additional information about the 
commands by pressing PF 1-a second time. 


LRUN — Display a System List 


Purpose To display a list of selected objects in the workspace. 
Syntax LRUN N 
N is one of the following: 
a selection expression 
specifies a combination of characters to be used for selecting names to 
appear in the list. Asterisks may be used to represent zero or more 
characters. 


a matrix of object names 
contains a list of the names to be included in the list. 


empty all objects in the workspace are displayed. 
Example LRUN '*PAN** 


Result Displays a list of all objects containing the letter combination PAN. 


Usage Notes 


The list is displayed and can be scrolled if the objects do not fit on to 


one screen. Commands and PF keys are available for performing 
operations on the items in the list. To see a list of the available 
commands, press the HELP key from the list. 
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LRUN and MASTER 


LRUN — Display a User List 


Purpose To display a list created with LDESIGN and to allow commands and PF keys to be used 
on objects in the list. 


Syntax. L LRUN N1 (N2) 
L isthe name of a user-defined list created with LDESIGN. 
N1 is a character matrix to be displayed to the left in the list. This is often a list of names. 


N2 isa character matrix to be displayed to the right in the list. Often this is a short 
description of the items on the left. 


Example ‘NUMBLIST' LRUN ( TELNUMB)( NAMES) 
Result Displays a list called NUMBLIST that was created with LDESIGN. The left column of the 


list contains telephone numbers (7TELNUMB) and the right column contains names 
(NAMES). 


Usage Notes 
The list is displayed and can be scrolled if the objects do not fit on to 
one screen. Any commands and PF keys defined in LDESIGN are 
made available. 


MASTER — Display Application Prototype Environment Top Menu 


Purpose To display the main menu of Application Prototype Environment. 
Syntax MASTER 


Usage Notes 
Displays the main menu of Application Prototype Environment. 


You return to the main menu from any other menu in the product by 
entering an equal sign or MASTER on the command line, or by 
pressing PF 4. 
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MDESIGN and MLIST and MRUN 


MDESIGN — Display MDESIGN Menu 


Purpose To call the Menu Design menu. 


Syntax MDESIGN 


Usage Notes 
Displays a menu containing options for designing both individual 
menus and integrated menu applications. 


MLIST — Display List of Menus 


Purpose To display a list of user-created menus. 
Syntax MLIST 


Usage Notes 
You can use commands and PF keys to perform operations on the 
menus in the list. Press PF 1 from the list to display the available 
commands. You can display additional information about the 
commands by pressing PF 1 a second time. 


MRUN — Invoke a Menu 


Purpose To display a menu and link all other menus belonging to the same menu application system. 
Syntax MRUN M 
M isa character string containing the name of a menu created with MDESIGN. 


Example MRUN 'MENUO2' 
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SYSTEM 


Usage Notes 
The specified menu is displayed and any other menus belonging to 
the same menu application system are linked. Options, commands, 
and PF keys defined for this menu are made available. 


SYSTEM — Display SYSTEM Menu 


| Purpose To call a menu containing options for various system controls and operations. 


Syntax SYSTEM 


Usage Notes 
A menu is displayed with options for various system operations such 
as modifying system profiles, changing to another national language, 
and converting libraries from Version 1 to Version 2 of Application 
Prototype Environment. 
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Glossary 


This glossary lists only terms which are unique to 
Application Prototype Environment, or which have 
particular meanings in Application Prototype 
Environment. For a complete listing of data processing 
terminology, see Vocabulary for Data Processing, 
Telecommunications, and Office Systems. 


action panel. ‘This is a panel where data is entered or 
options are selected. 


access method. The method used when reading or 
writing data to from a file, usually on disk (exception 
INSTOR and DUMMY). The method used depends on 
the physical properties of the file. Therefore, the file and 
the access method are sometimes synonymous. Some 
access methods allow access to a relative record, that is, 
to a specific record number in the file. Data base access 
methods also allow access to records by data keys. 


access function. An APL function used to control 
access to a certain type of file (including instorage files). 
All functions used for file handling will call an access 
function to read and write to the file. 


access path. For a file supporting direct access via a 
key, the access path describes which field contains the 
key. Certain implementations of direct access files can 
have multiple access paths, meaning alternate keys to 
the same information. The primary access path uses the 
primary key to access the data and has the same name 
as the file. Alternate access paths have different names 
and will reference different variables to obtain a key, but 
will use the declaration of the file (the primary access 
path) to control the layout of the file records. 


auxiliary processor. A program that cooperates with 
the API. interpreter to communicate with facilities 
external to APL. For example, AP126 provides 
communication between APL and GDDM. 


application. A menu system as created with Menu 
Design (DESIG) 


book. See “tutorial book.” 
browse. When information displayed in a window on 


a screen extends beyond the limits of the window, the 
window can be moved up down or left right over the 


information using Program Function (PF) keys. The 
user can thus view any part of the data. This also 
applies to tutorial pages. 


chart. A graphical representation of data. The chart 
can employ different graphical principles (line graph, 
surface chart, bar chart, pie chart, and so on) to display 
a set of dependent variables (called the components of a 
chart) as a function of one or more independent 
variables. 


chart function. A function containing necessary 
statements to initiate and contro! PGF to build a chart 
on the screen based on variables in the workspace. At 
the normal end of CDESIGH, a chart function is 
generated. When executed, the chart function uses the 
dynamic content of defined variables. 


cover function. An APL function used to perform a 
normally complicated action through an auxiliary 
processor. The cover function provides a simple, high 
level interface to the auxiliary processor. 


current panel. ‘The current panel is the panel 
displayed on the screen or, if not displayed, the one last 
displayed or made current with the SDI SP function. 


current tutorial, This is either the tutorial book 
pointed out in the topmost entry in the current tutorial 
stack, that is, the book next to be used when the HELP 
key is pressed, or if tutorial mode has been entered, the 
tutorial book viewed. 


current tutorial page. The specific page pointed out by 
the last SHELP function call. 


current tutorial stack. The current tutorial stack is the 
one set by the last SHEL P function call. 


datum line. A line drawn in a chart from which all 
components will be plotted. If no special datum line is 
specified the X- or Y-axis is used 


declaration. Specification of the format of a record in 
a file and the data conversion required as specified in 
the declaration. Data formats in the declaration are the 
same as the data formats in the record. Specifies the 
placement of APL variables into fields in files. 
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dummy file. A special type of file to allow a fast test of 
the file handling in an application. It allows all data to 
be written to it, and returns predefined information 

when referenced. No data is actually stored. 


GDDM. Graphical Data Display Manager, IBM 
Program Product $748-XXH. 


grid lines. Lines drawn in a chart perpendicular to a 
certain axis to indicate the projection of the tickmarks of 
the axis onto the chart components. 


image. A graphical pattern such as a logotype or icon 
created with Image Design (IDES TGN). 


instorage file. A file that allows storing and retrieval 
of information as a matrix in the APL workspace and 
can be manipulated by APL instructions. 


keyed access. Access to data where the record 
retrieved or stored is determined through a key. The 
key can be one or several fietds from the record. 


label. Name given to a field in a panel or to a record 
ina file. The tabel associates the field or record with an 
APL variable of the same name. The same label might 
be used for both a panel and a record. 

label list. A name list of label names. See name list. 
legend. A table containing a list of chart components, 
showing the colors and line types used to represent each 
one. The legend is normally centered at the right-hand 

margin. 


list. A list created with List Design (LDESIGH). 


menu, A menu selection panel created with Menu 
Design (MDESIGH). Menus that are linked together 
belong to the same application. 


name list. A list of names in a character vector, a 
matrix, or a vector of vectors. Names in a character 
vector are normally separated by blanks, commas, or 
slashes. A matrix might contain rows of names that are 
separated in the same way as for character vectors. 
Each clement in a vector of vectors must be a single 
name to qualify as a name list. 


object. 
library: 


Objects that can be saved in an APELIB2 


menu application 
chart 

file declaration 

APL latent expression 
APL function 

library group 

image 


list 

menu 

APL operator 
panel 

query 

APL variable 
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object library. A file in which objects from a 
workspace can be stored. 


object library system. A group of functions for 
creating object libraries and storing and retrieving 
functions and variables in them. 

object list. A name list of object. See name list. 
panel. Specification of a display screen layout 
containing windows in which data (in APL variables) 
can be displayed or entered. One graphics field may be 
specified on the panel. 


panel list. A name list of panel names. Sec name list. 


PGF. Presentation Graphics Feature of GDDM. A 
component under GDDM that allows creation of 

presentation graphics. 
primary access path. Sce “access path.” 


query. An SQL statement that performs an operation 
on an SQL, DS or a DB? data base. 


relative record access. Access to data where the 
record retrieved or stored is determined through its 
position in the file. The relative position is specified 
through a variable used as a pointer. 


sequential access. | When storing data, records are 
stored in the sequence in which they are specified. 
When rewrieving data, records are read in the same 
order as they were stored. 


table. An SQL file consisting of a defined number of 
(vertical) columns and some number of unordered. 
(horizontal) rows. 


tutorial book. A collection of tutorial panels that 
together form a “book” describing a part of an 
application. 


tutorial panel. A panel built specially to act as guiding 
information for parts of an application. A tutorial panel 
is defined in the same way as a normal panel. 


view. An alternate and temporary representation of 
data from one or more tables. 


window. A ficld on a display screen used to display 
and alter an APL variable. 
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access function, glossary 229 
access keys, sorting 109 
access methods, summary 9$ 
access path, glossary 229 
accessing files 93 
action panel, glossary 229 
adding records to a file 107 
ADMPRINT files 
use with SPRI 69 
use with SPRIGRA 70 
use with SPRIX 71 
ADMSAVE files 
use with SFSAVE 45 
use with SFSHOW 46 
ADMSYMBL filetype 59 
alarm, audible 9 
aligning an array 184, 196 
altering PF keys 12, 30 
altering the processing sequence 30 
applications, for menus 220 
arrays 
converting to upper case 213 
deleting characters 174, 175 
deleting multiple blanks 175 
deleting trailing blanks 177 
deleting trailing characters 178 
dropping elements 177 
each on left 179 
each on right 180 
finding first element 170 
finding last element 171 
left alignment 184 
pervasive on left 194 
pervasive on right 194 
removing underscores 198 
replacing elements 197 
right alignment 196 
shape 160, 208 
sorting 181 
taking elements 212 
unique elements 214 
audible alarm 9 
auxitiary functions 
AUXILS 138 
CHARTOUT 87 
S_COPY 162 
DCLCOPY 158 
DCONVERT 159 
S_DSPLY 160 
A_FNS 162 
A_HELP 163 
list of 158 
AL NMS 163 


A_OPS 164 

PANELCOPY 16l 

PCONVERT 161 

A_SHOW 164 

à _STOP 165 

A_TME 166 

S_TRACE 167 

A_VARS 167 
auxiliary processor 

error handling 38, 201 
auxiliary processor, glossary 229 
AUXILS function 158 


blanks, deleting multiple 175 

blanks, deleting trailing 177 

blinking field 55 

box function 171 

break first function 170 

break last function 171 

A_BRF function 170 

bright field 57 

A_BRE fonction 171 

browse, glossary 229 

browsing and editing variables 
SBRHOD function 10 

browsing instorage files 108 

browsing variables 11, 16 

A_BX function 171 


A_C function 172 
call number 139 
CAND function 86 
catalog names, defining 150 
CDESIGN function 86 
CDROP function 218 
CHAFNS function 86 
changing key usage, SBRKEYS 12 
characters, converting to numerics 215 
chart definition 85 
chart design 
PGF functions 91 
starting 86 
chart function, glossary 229 
chart functions 
CAND 86 
CDESIGN 86 
CHAFNS 86 
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CHARTSETUP 88 
CLIST 88 
PGF 91 
Vs 89 
chart, glossary 229 
CHARTOUT function 87 
CHARTSETUP function 88 
CLEAR key, see if used 57 


clearing 
current panel 38 
fields 44 


graphics fields 6 
CLIST function 88 
CLOAD function 219 
A CMD function 173 
CMS files 

setting type and mode 108 
codes, object type 2 
colors 

at element level 80 

specifying with SCOL and SCOLI 39 
command function 173 
commands, sending 182, 209 
comment lines, displaying 183 
compatibility functions 223 
compress function 172 
controls, setting 199 


converting 
characters to numerics 215 
libraries 223 


A_COPY function 162 
COPY _ID function 6,69, 70 
correcting numeric input 205 
cover function, glossary 229 
creating screen hardcopy 69, 70 
CURRENT keyword 200 
current page of tuloria!, setting 48 
current panel 

definition 1 

find shape of 47 

glossary 229 

setting 42 
current slate, SBRSTATE 14 
current tutorial page, glossary 229 
current tutorial stack, glossary 229 
current tutorial, glossary 229 
cursor position 

in graphic fields 78 
cursor-handling functions: 

SCUR, SCURT, set cursor position 41 

SQCUR 73 

SQCUR, find specified fields 73 


datum line, glossary 229 
DCLCOPY function 158 
DCONVERT function 159 
DEBUG keyword 201 
declaration, glossary 229 
declarations 
See files 
declarations, list of 96 
definition of terms 229 
definitions 
current panel 1 
declaration 93 
filename 93 
label list 1 
library names 125 
object list 1 
panel list 1 
DELETE query 113 
deleting 
characters 174, 175 
lines 19 
mulüple blanks 175 
trailing blanks 177 
trailing characters 178 
design components 
CDESIGN 86 
DOCUMENT 220 
FDESIGN 102 
IDESIGN 221 
LDESIGH 222 
loading into workspace 219 
MDESIGN 226 
menu for 219 
ODESIGN 134 
PDESIGN 8 
QDESIGN 113 


removal from workspace 152, 218 


DESIGN function 219 
DIALOG function 220 
discarding object libraries 136 
displaying panels 

SDTUT 43 

SINP S6 

SMOD 60 

SOUT 68 
DLIST function 96 
A _DLTC function 174 
A DMB function 175 
A_DME function 175 
4_DOC function 176 
DOCUMENT function 220 
documenting 

an application 220 

objects 176 
dropping elements from arrays 
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A_DRP function 177 
A_DSPLY function 160 
A_DTB function 177 
A_DPC function 178 
dummy files 98 

duplicate key 99 

duplicate quotes function 195 
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A_E function 179 
cach on left operator 179 
each on right operator 180 
editing SQL tables 114 
editing variables 

SBRMOD function 10 
A_ELA function 179 
enable exit processing 35 
ENTER key, see if used 58 
ENVIRON keyword 202 
A_ERA function 180 
erasing 

files 97 

objects 138 

records from a file 100 
erasing objects 147 
error 

handling 201 

information 163 
execution time, measuring 166 
execution, halting 182 
exit processing, enabling 35 
expand function 179 
EXPAND keyword 203 
expanding paneis 203 
expunging objects 147 


FCLOSE function 97 
FDESIGN function 102 
FDROP function 97 
FDUMMYOPT function 98 
FDUPK function 99 
FEOF function 99 
FERASE function 100 
FERR function 100 
FGET function 101 
FGETHOLD function 101 
field attributes, resetting 74 
resetting 74 
field handling functions 
SBMOD 9 


SCOLI and SCOLI, field color 
SERA and SERATI, clear fields 


SHAPE 47 
SHLT and SHLTT, set highlighting 55 
SINT and SINTI, set intensity 57 
SLOADPS 59 
SMODF 64 
SNUMRC, check numeric input 67 
SPSS and SPSSI 72 
SRESET 74 
SPYP and STYPL, specify field type 76 
SWRI and SWRIT, specify data 77 
field intensity, setting 57 
field shapes 47 
ficld types, setting 76 
fields, modified 64 
FIFO execution 195 
file design 102 
file number, object library 137 
fite-handling functions 
DLIST 96 
FCLOSE 97 
FDESIGN 102 
FDROP 97 
FDUMMYOPT 98 
FDUPK 99 
FEOF 99 
FERASE 100 
FERR 100 
FCET 101 
FGETHOLD 101 
FILEFNS 102 
FILESIZE 103 
FKNOTF 104 
FLKEY 104 
FPOSITION 105 
FREAD 105 
FREADHOLD 106 
FRECS 106 
FSET 107 
FWRITE 107 
file-handling variables 
Fr 108 
INSS 109 
PCODES 109 
RCODE 110 
PILEFNS function 102 
files 
adding records 107 
converting 159 
copying 158 
erasing 97 
erasing records 100 
key last used 104 
number of records in 106 
reading from 105 
replacing records 107 
updating 101 
writing to 107 
FILESIZE function 103 
FKNOTF function 104 
FLKEY function 104 
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A_FNS function 162 


FPOSITION function 105 


FREAD function 105 


FREADHOLD function 106 


FRECS funcion 106 
FREE query 113 
FSET function 107 
EZ variable 108 
functions 
comment lines 183 
listof 162, 221 


FUNCTIONS funcion 221 


FWRITE function 107 


CCLEAR function 6 
GCUR global variable 78 
GDDM 

communicating directly 


image symbol editor 59 


paging facilities 206 

PGF functions 91 

return codes 38 
GDDM function 7 
GDDM. glossary 230 


general screen-handling functions 


GCLEAR 6 
GDDM 7 

SALE 9 
SCLEAR 38 
SCREENTYPE 40 
SDISP 42 
SDPUT 43 
SFSAVE 45 
SFSHOW 46 
SHELP 48 


SPRIGRA 70 

SPRIX 71 
global variables 

é 


B78 
PB 

QETEM 134,149 
EL 135, 150 


QNPARMS 134, 135, IS} 


COPY_ID 69 
glossary 229 
grade function 181 
Graphical Display Manager, see GDDM 
graphics fields 
clearing 6 
cursor position 78 
A_GRD function 181 
grid lines, glossary 230 


halt execution 182 
hardcopy of screen 69, 70 
HELP global variable 78, 163 
help information 3, 164 
highlighted fields 55 
highlighting 

at element level 81 
A_HLT function 182 
A_HOST function 182 
host system, initiating 202 
A_HOW function 183 
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IDENTIFY keyword 203 
IDESIGN function 221 
ILIST function 221 
image symbol edito 59, 207 
images 

designing 221 

list of 221 
initialization function 25, 26 
A_INP function 184 
input checking 20$ 
input function 184 
INSERT query 113 
inserting tines 19 
ILUSS function 109 
instorage files, glossary 230 
INSTORDSP function 108 
invisible field 57 
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key not found 104 
key, duplicate 99 
key, last used 104 
keyed access, glossary 230 


label fist, glossary 230 
A_LAL function 184 
LANGUAGES function 222 
languages, switching 191, 222 
LDESIGN function 222 
left align function 184 
legend, glossary 230 
LIBCONV function 223 
LIBFNS function 130 
LIBMSG keyword 204 
libraries 

See object libraries 
LIBRARIES function 130 
library names 

defining t49 

defining in TSO 150 
light pen 76 
list function 185 
LISTLIB function 131 
lists 

designing 222 

displaying 224, 225 

list of 224 
LLIST functién 224 
loading symbol storage 59 
logical PF keys 59 
LRUN function 224, 225 
&_LST function 185 
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A_MAD function 186 
main menu, displaying 225 
A _MAR function 186 
A_MAS function 187 
MASTER function 225 
matrices 
combining 186, 187 
converting to vectors 190 
creating from arrays 171 


finding indices 188 
finding membership 187 
listing words 185 
object names 193 
removing blanks 198 
selecting names 189 
sorting 210 
matrix add downwards function 186 
matrix add repeated function 186 
matrix add sideways function 187 
matrix membership function 187 
matrix select function 189 
matrix to vector-of-vectors 190 
matrix-to-matrix index 188 
MDESIGN function 226 
menu applications, starting 220 
menus 
designing 226 
displaying 226 
listof 226 
messages 
error information 163 
for libraries 140, 151, 204 
for queries 116 
identifiers 203 
immediate display 65 
placing on screen 65 
tutorial mode 43 
miscellaneous functions 
CDROP 218 
CLOAD 219 
DESIGN 219 
DIALOG 220 
DOCUMENT 220 
FUNCTIONS 221 
IDESIGN 221 
ILIST 221 
LANGUAGES 222 
LDESIGN 222 
LIBCONV 223 
LLIST 224 
LRUN 224, 225 
MASTER 225 
MDESIGN 226 
MLIST 226 
MRUN 226 
SYSTEM 227 
MLIST function 226 
4_MHM function 187 
A_MMTI function 188 
modified fields 64 
moving lines 18 
MRUN function 226 
MSG variable 65 
4_MSE function 189 
A_M2VV function 190 
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name list, glossary 230 
naming conventions 2, 128 
A_NLT function 191 

4_NMS function 163 

NULLS keyword 205 
NUMACCEPT keyword 205 
numeric input checking 67, 205 
numerics, converting from characters 
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object cłasses function 192 
object libraries 
automatic search 144 
call number 139, 147 
converting 223 
erasing objects 138 
expunging objects 147 
file characteristics 132 
file number 137 
index of 131,141 
list of 130, 142 
messages 246, 151, 204 
naming conventions 128 
putting objects in 146 
resetting defaults 148 
retrieving objects 139, 143 
return codes 125, 153, 155 
storing library objects 146 
type codes 2, 126 
utilization 132 
object library functions 
LIBFNS 130 
LIBRARIES 130 
LISTLIB 131 
OCHECK 132 
OCLOSE 133 
OCREATE 134 
ODESIGN 134 
ODROP 136 
OEND 137 
OERASE 138 
OGET 139 
OHELP 140 
OINDEX 141 
OLIST 142 
OLOAD 143 
OOPEN 144 
OPGET 145 
OPUT 146 
OSCRUB 147 
OSETDFLT 148 
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object library system, glossary 230 
object library variables 

QETEM 149 

OLEVEL 150 
151 


QRC2 155 
object library, glossary 230 
object list function 193 
object type codes 2, 126, 192 
object, glossary 230 
objects, displaying 224, 225 
objects, list of 163 
objects, verifying 216 
4_OC function 192 
OCHECK function 132 
OCLOSE function 133 
OCREATE function 134 
ODESIGN function 134 
ODROP function 136 
OEND function 137 
OERASE function 138 
QETEM variable 134, 149 
OGET function 139 
OHELP function 140 
OINDEX function 141 
&_OL function 193 
OLEVEL global variable 135, 150 
OLIST function 142 
OLOAD function 143 
online information 3, 164 
ONPARNS global variable 134, 15] 
OOPEN function 144 
operating environment, initiating 202 
operators, list of 164 
OPGET function 145 
A_OPS function 164 
OPUT function 146 
ORC variable 125, 153 
QRC? variable 125, 155 
OSCRUB function 147 
OSETDFLT function 148 
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PA key, see if used 58 
PAGING keyword 206 
panel design 8 
panel list, glossary 230 
panel modification, setting 200 
panel performance 206 
panel usage functions 
SBRKEYS 12 
SBRMOD 10 
SBROUT 11 
SBRSTATE 14 
SBRWINDOW 15 
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SINP 56 
SMOD 60 
SOUT 68 
panel, glossary 230 
PANELCOPY function 16l 
panels 
checking numeric input 205 
converting 161 
copying 16) 
creating & 
listing 9 
paging with GDDM 206 
restoring when saved 74 
saving contents 75 
setting as current 42 
setting expansion 203 
setting modification 200 
testing input 63 
PANFNS function 8 
PCODES global variable 
PCONVERT function 161 
PDESIGN function 8 
pen-selectable fields 76 
performance for panels 206 
performance, improving 62 
pervasive on left operator 194 
pervasive on right operator 194 
PF key actions, SBRMOD/SBROUT 32 
PF keys 
altering 30 
SBRMOD 10 
seting 79 
SMOD 61 
tutorials 43 
PF keys, see if used 58, 59 
PEKEY global variable 79, 80 
PGF support functions 91 
PGF, glossary 230 
A_PLA function 194 
PLIST 9 
positioning record pointer 105 
A_PRA function 194 
Presentation Graphics Feature, see PGF 
primary access path, see access path 
printing objects 176, 220 
processing functions 26, 28 
processing sequence, altering 30 
processing states 27 
product functions, list of 221 
product top menu 225 
profiles, for system 227 
programmable symbols 59 
prompting for input 184 
PSS 59 
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QCREATE function 112 
QDESIGN function 113 
QEDIT function 113 
QEXEC function 114 
QHELP function 16 
QINSERT function 117 
QLIST function 118 
QMOD function 119 
QPRICL variable 123 
A_QQ function 195 
QRC function 120 
QRUN function 121 
A_QUE function 195 
queries 
creating 112 
designing 122 
executing 121 
imbedding 112 
listing 118 
modifying 113 
TSO print files 123 
QUERIES function 122 
query functions 
Q@CREATE 112 
QDESIGN 113 
QEDIT 113 
@EXEC 114 
QHELP 116 
QINSERT 117 
QLIST 118 
QMOD 119 
QPRICL 123 
QRC 120 
QRUN 121 
QUERIES 122 
SQLFNS 122 
TABLES 122 
FLIST 123 
query types 113 
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A_RAL function 196 
RCODE global variable 110 
reading from a file 105 
reading input from panels 56 
redisplaying a panel 38 
reduce matrix function 198 
remove underscores function 198 
A_REP function 197 
replacing elements 197 
replacing records in a file 107 
resetting field attributes 74 
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restoring saved panels 74 
return codes 

file access 109 

for OCHECK 132 

for OCLOSE 133 

for OCREATE 135 

for ODROP 136 

for OEND 137 

for OERASE 138 

for OINDEX 141 

for OLIST 142 

for OLOAD 143 

for OOPEN 144 

for OPGET 145 

for OPUT 146 

for OSCRUB 148 

for OSETDFLT 148 

library operations 153 

query operations 120 
reverse video field 55 
right align function 196 
A_RM function 198 
S_RU function 198 


SALE function 9 
saving panel contents 75 
SBMOD function 9 
SBRKEYS function 12 
SBRKEYS, processing functions 28 
SBRMOD function 10, 16 
SBRMOD;SBROUT 

example of 16, 20 

initialization function 25 

PF key actions 32 

processing function 26 

scrolling 20 

terminating 34 
SBROUT function 11, 16 
SBRSTATE function 14 


SBRSTATE, processing functions 28 


SBRWINDOW function 15 
SBRWINDOW, processing functions 
SCHK function 38 
SCLEAR function 38 
SCOL and SCOLI functions 39 

cotors at element level 80 
screen attributes 

display with SCREENTYPE 40 
screen hardcopy, creating 69, 70 
screen messages 

SMSG 65 
screen-handling 

creating tutorials 49 

making hardcopies 69, 70 
screen-handling functions 
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COPY_ID 6 

GCLEAR 6 

GCUR 78 

GDDM 7 

HELP 78 

PANENS 8 

PDESIGN 8 

PFKEY 19 

PLIST 9 

SALE 9 

SBMOD 9 

SBRKEYS 12 

SBRMOD 10 

SBROU? 1l 

SBRSTATE 14 

SBRWINDOW 15 

SCHK 38 

SCLEAR 38 

SCOLI, SCOLI 39 

SCREENTYPE 40 

SCUR, SCURI 41 

SDISP 42 

SDTUT 43 

SERA, SERAI 44 

SFSAVE 45 

SFSHOW 46 

SHAPE 47 

SHELP 48 

SHLT,SHLTI 38 

SINP 56 

SINT, SINTI 57 

SKCL 57 

SKEN 58 

SKPA 58 

SKPF 58 

SKPL 59 

SLOADPS 59 

SMOD 60 

SMODF 64 

SMSG 65 

SNUMRC 67 

SOUT 68 

SPRI 69 

SPRIGRA 70 

SPRIX 71 

SPSS, SPSSI N 

SRESET 74 

SREST 14 

SSAVE 75 

STYP, STYPI 76 

SWRI, SWRII 177 
SCREENTYPE function 40 
scroll groups 

moving lines 18 
scrolling variables 11, 16 

SBRMOD function 10 
SCUR and SCURI functions 41 
SDISP function 

description 42 


SDTUT function 43 
SELECT query 113 
selectable field 76 
selecting objects 224, 225 
sending commands 182, 209 
sequential access, glossary 230 
SERA and SERAI functions 44 
session manager commands 209 
A_SET function 199 
CURRENT 200 
DEBUG 201 
ENVIRON 202 
EXPAND 203 
IDENTIFY 203 
LIBMSG 204 
NULLS 205 
NUMACCEPT 205 
PAGING 206 
SPRIXIMG 207 
setting 
controls 199 
current panel 42 
field highlighting 55 
field intensity 57 
field type 76 
next state 28 
PF keys 79 
SFSAVE function 45 
SFSHOW function 46 
SHAPE function 47 
shape of arrays 160, 208 
SHELP function 48 
SHET and SHLTI functions 55 
A_SHOW function 164 
4_SHP function 208 
SINP function $6 
SINT and SINTI functions 57 
size of a file 
defining 103 
querying 106 
SKCL function 57 
SKEN function 58 
SKPA function 58 
SKPF function 58 
SKPL function 59 
SLOADPS function 59 
4_SMGR function 209 
SMOD function 60 
SMODF function 64 
SMSG function 65 
SNUMRC function 67 
sorting 
arrays 181 
matrices 210 
sound alarm 9, 65 
SOUT function 68 
specifying data in fields 77 
SPRI function 69 
SPRIGRA 
making hardcopies 70 


SPRIGRA function 70 
SPRIX function 71 
SPRIXIMG keyword 207 
SPSS and SPSSI functions 72 
SQCUR function 73 
SQL queries 
See, queries 
SQL tables 
See tables 
SQLENS function 122 
SRESET function 74 
SREST function 74 
A_SRT function 210 
SSAVE function 75 
stack for GDDM paging 206 
stacking 
expressions 195 
tutorials 51 
states 
processing 27 
SBRSTATE function 14 
setting 28 
A_STOP function 165 
stop vectors, setting 165 
STYP and STYPT functions 76 
switching languages 191, 222 
SWRI and SWRIT functions 77 
symbol storage 
loading and setting 59, 207 
system controls, setting 227 
SYSTEM function 227 
system profiles 227 
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table for GDDM paging 206 
tables 

designing 122 

editing data 119 

inserting data 117 

listing 123 

modifying 114 
TABLES function 122 
taking elements from arrays 212 
S_TE function 211 
terminal attributes 40 
terminology 229 
testing commands 173 
time display 212 


time edit function 
A_TKE function 
PLIST function 
A_TME function 
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top menu, displaying 225 
A_TRACE function 167 
trace vectors, setting 167 
trailing blanks, setting 205 
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A TS function 212 A_MAS 187 


tutorial book, glossary 230 A_MM 187 
tutorial panel, glossary 230 A_MMI 188 
tutorial stack 78 A_MSL 189 
tutorials A _M2VV 190 
combining 50 A_ NLT 191 
creating 49 4_0C 192 
data input 52 A_OL 193 
entering tulorial mode 43 &_PLA 194 
example 53 A&_PRA 194 
find name of current page 78 AQQ 195 
for product functions 3, 164 A_QUE 195 
initiating 48 A_ RAL 196 
stacking 51 A REP 197 
system tutorial 37 A_RM 198 
system, display with SBRMOD 10 A_RU 198 
type codes 2, 126 A_SET 199 
A_SHP 208 
A _SMGR 209 
A_SRT 210 
6_TE 211 
A_TKE 212 
A_TS 212 
A_UC function 213 A_UC 213 
underscored field 55 A_UNIQ 214 
A_UNIQ function 214 A VNI 25 
unique function 214 A VOC 216 
UPDATE query 113 UTILS 170 
updating files 101 UTILS function 170 


upper case function 213 
utility functions 


A BRF 170 

A_BRL 171 

A_BX 171 

à C 172 

A_CMD 173 variables 

A_DLTC 174 browsing 16 

S_DMB 175 browsing and editing 10 
A_DMC 175 variables, list of 167 

A_DOC 176 variables, see global variables 
S_DRP 177 &_VARS function 167 
A_DTB 177 verify object class function 216 
A_DTC 178 A_VNI function 215 

AE 179 A_VOC function 216 

O_ELA 179 VS function (charts) 89 
ALERA 180 

A_ GRD 181 

A_HLT 182 

A_HOST 182 

A HOW 183 

A_INP 184 

A LAL 184 window coordinates 34 

A LST 185 window coordinates, find and set 15 
A MAD 186 window, glossary 230 

A MAR 186 windows, SBRWINDOW function 15 


writing to a file 107 
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